monitor-ci

# Monitor CI Command You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn subagents to interact with Nx Cloud, run deterministic decision scripts, and take action based on the results. ## Context - **Current Branch:** !`git branch --show-current` - **Current Commit:** !`git rev-parse --short HEAD` - **Remote Status:** !`git status -sb | head -1` ## User Instructions $ARGUMENTS **Important:** If user provides specific instructions, respect them over default behaviors described below. ## Configuration Defaults | Setting | Default | Description | | ------------------------- | ------------- | ------------------------------------------------------------------------- | | `--max-cycles` | 10 | Maximum **agent-initiated** CI Attempt cycles before timeout | | `--timeout` | 120 | Maximum duration in minutes | | `--verbosity` | medium | Output level: minimal, medium, verbose | | `--branch` | (auto-detect) | Branch to monitor | | `--fresh` | false | Ignore previous context, start fresh | | `--auto-fix-workflow` | false | Attempt common fixes for pre-CI-Attempt failures (e.g., lockfile updates) | | `--new-cipe-timeout` | 10 | Minutes to wait for new CI Attempt after action | | `--local-verify-attempts` | 3 | Max local verification + enhance cycles before pushing to CI | Parse any overrides from `$ARGUMENTS` and merge with defaults. ## Nx Cloud Connection Check Before starting the monitoring loop, verify the workspace is connected to Nx Cloud. Without this connection, no CI data is available and the entire skill is inoperable. ### Step 0: Verify Nx Cloud Connection 1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken` 2. **If `nx.json` missing OR neither property exists** → exit with: ``` Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud ``` 3. **If connected** → continue to main loop ## Architecture Overview 1. **This skill (orchestrator)**: spawns subagents, runs scripts, prints status, does local coding work 2. **ci-monitor-subagent (haiku)**: calls one MCP tool (ci_information or update_self_healing_fix), returns structured result, exits 3. **ci-poll-decide.mjs (deterministic script)**: takes ci_information result + state, returns action + status message 4. **ci-state-update.mjs (deterministic script)**: manages budget gates, post-action state transitions, and cycle classification ## Status Reporting The decision script handles message formatting based on verbosity. When printing messages to the user: - Prepend `[monitor-ci]` to every message from the script's `message` field - For your own action messages (e.g. "Applying fix via MCP..."), also prepend `[monitor-ci]` ## Anti-Patterns These behaviors cause real problems — racing with self-healing, losing CI progress, or wasting context: | Anti-Pattern | Why It's Bad | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | Using CI provider CLIs with `--watch` flags (e.g., `gh pr checks --watch`, `glab ci status -w`) | Bypasses Nx Cloud self-healing entirely | | Writing custom CI polling scripts | Unreliable, pollutes context, no self-healing | | Cancelling CI workflows/pipelines | Destructive, loses CI progress | | Running CI checks on main agent | Wastes main agent context tokens | | Independently analyzing/fixing CI failures while polling | Races with self-healing, causes duplicate fixes and confused state | **If this skill fails to activate**, the fallback is: 1. Use CI provider CLI for a one-time, read-only status check (single call, no watch/polling flags) 2. Immediately delegate to this skill with gathered context 3. Do not continue polling on main agent — it wastes context tokens and bypasses self-healing ## Session Context Behavior If the user previously ran `/monitor-ci` in this session, you may have prior state (poll counts, last CI Attempt URL, etc.). Resume from that state unless `--fresh` is set, in which case discard it and start from Step 1. ## MCP Tool Reference Three field sets control polling efficiency — use the lightest set that gives you what you need: ```yaml WAIT_FIELDS: 'cipeUrl,commitSha,cipeStatus' LIGHT_FIELDS: 'cipeStatus,cipeUrl,branch,commitSha,selfHealingStatus,verificationStatus,userAction,failedTaskIds,verifiedTaskIds,selfHealingEnabled,failureClassification,couldAutoApplyTasks,autoApplySkipped,autoApplySkipReason,shortLink,confidence,confidenceReasoning,hints,selfHealingSkippedReason,selfHealingSkipMessage' HEAVY_FIELDS: 'taskOutputSummary,suggestedFix,suggestedFixReasoning,suggestedFixDescription' ``` The `ci_information` tool accepts `branch` (optional, defaults to current git branch), `select` (comma-separated field names), and `pageToken` (0-based pagination for long strings). The `update_self_healing_fix` tool accepts a `shortLink` and an action: `APPLY`, `REJECT`, or `RERUN_ENVIRONMENT_STATE`. ## Default Behaviors by Status The decision script returns one of the following statuses. This table defines the **default behavior** for each. User instructions can override any of these. **Simple exits** — just report and exit: | Status | Default Behavior | | ----------------------- | ---------------------------------------------------------------------------------------------------------------- | | `ci_success` | Exit with success | | `cipe_canceled` | Exit, CI was canceled | | `cipe_timed_out` | Exit, CI timed out | | `polling_timeout` | Exit, polling timeout reached | | `circuit_breaker` | Exit, no progress after 5 consecutive polls | | `environment_rerun_cap` | Exit, environment reruns exhausted | | `fix_auto_applying` | Self-healing is handling it — just record `last_cipe_url`, enter wait mode. No MCP call or local git ops needed. | | `error` | Wait 60s and loop | **Statuses requiring action** — when handling these in Step 3, read `references/fix-flows.md` for the detailed flow: | Status | Summary | | ------------------------ | --------------------------------------------------------------------------------------------- | | `fix_auto_apply_skipped` | Fix verified but auto-apply skipped (e.g., loop prevention). Inform user, offer manual apply. | | `fix_apply_ready` | Fix verified (all tasks or e2e-only). Apply via MCP. | | `fix_needs_local_verify` | Fix has unverified non-e2e tasks. Run locally, then apply or enhance. | | `fix_needs_review` | Fix verification failed/not attempted. Analyze and decide. | | `fix_failed` | Self-healing failed. Fetch heavy data, attempt local fix (gate check first). | | `no_fix` | No fix available. Fetch heavy data, attempt local fix (gate check first) or exit. | | `environment_issue` | Request environment rerun via MCP (gate check first). | | `self_healing_throttled` | Reject old fixes, attempt local fix. | | `no_new_cipe` | CI Attempt never spawned. Auto-fix workflow or exit with guidance. | | `cipe_no_tasks` | CI failed with no tasks. Retry once with empty commit. | **Key rules (always apply):** - **Git safety**: Stage specific files by name — `git add -A` or `git add .` risks committing the user's unrelated work-in-progress or secrets - **Environment failures** (OOM, command not found, permission denied): bail immediately. These aren't code bugs, so spending local-fix budget on them is wasteful - **Gate check**: Run `ci-state-update.mjs gate` before local fix attempts — if budget exhausted, print message and exit ## Main Loop ### Step 1: Initialize Tracking ``` cycle_count = 0 # Only incremented for agent-initiated cycles (counted against --max-cycles) start_time = now() no_progress_count = 0 local_verify_count = 0 env_rerun_count = 0 last_cipe_url = null expected_commit_sha = null agent_triggered = false # Set true after monitor takes an action that triggers new CI Attempt poll_count = 0 wait_mode = false prev_status = null prev_cipe_status = null prev_sh_status = null prev_verification_status = null prev_failure_classification = null ``` ### Step 2: Polling Loop Repeat until done: #### 2a. Spawn subagent (FETCH_STATUS) Determine select fields based on mode: - **Wait mode**: use WAIT_FIELDS (`cipeUrl,commitSha,cipeStatus`) - **Normal mode (first poll or after newCipeDetected)**: use LIGHT_FIELDS Call the `ci_information` tool with the determined `select` fields for the current branch. Wait for the result before proceeding. #### 2b. Run decision script ```bash node <skill_dir>/scripts/ci-poll-decide.mjs '<subagent_result_json>' <poll_count> <verbosity> \ [--wait-mode] \ [--prev-cipe-url <last_cipe_url>] \ [--expected-sha <expected_commit_sha>] \ [--prev-status <prev_status>] \ [--timeout <timeout_seconds>] \ [--new-cipe-timeout <new_cipe_timeout_seconds>] \ [--env-rerun-count <env_rerun_count>] \ [--no-progress-count <no_progress_count>] \ [--prev-cipe-status <prev_cipe_status>] \ [--prev-sh-status <prev_sh_status>] \ [--prev-verification-status <prev_verification_status>] \ [--prev-failure-classification <prev_failure_classification>] ``` The script outputs a single JSON line: `{ action, code, message, delay?, noProgressCount, envRerunCount, fields?, newCipeDetected?, verifiableTaskIds? }` #### 2c. Process script output Parse the JSON output and update tracking state: - `no_progress_count = output.noProgressCount` - `env_rerun_count = output.envRerunCount` - `prev_cipe_status = subagent_result.cipeStatus` - `prev_sh_status = subagent_result.selfHealingStatus` - `prev_verification_status = subagent_result.verificationStatus` - `prev_failure_classification = subagent_result.failureClassification` - `prev_status = output.action + ":" + (output.code || subagent_result.cipeStatus)` - `poll_count++` Based on `action`: - **`action == "poll"`**: Print `output.message`, sleep `output.delay` seconds, go to 2a - If `output.newCipeDetected`: clear wait mode, reset `wait_mode = false` - **`action == "wait"`**: Print `output.message`, sleep `output.delay` seconds, go to 2a - **`action == "done"`**: Proceed to Step 3 with `output.code` ### Step 3: Handle Actionable Status When decision script returns `action == "done"`: 1. Run cycle-check (Step 4) **before** handling the code 2. Check the returned `code` 3. Look up default behavior in the table above 4. Check if user instructions override the default 5. Execute the appropriate action 6. **If action expects new CI Attempt**, update tracking (see Step 3a) 7. If action results in looping, go to Step 2 #### Tool calls for actions Several statuses require fetching additional data or calling tools: - **fix_apply_ready**: Call `update_self_healing_fix` with action `APPLY` - **fix_needs_local_verify**: Call `ci_information` with HEAVY_FIELDS for fix details before local verification - **fix_needs_review**: Call `ci_information` with HEAVY_FIELDS → get `suggestedFixDescription`, `suggestedFixSummary`, `taskFailureSummaries`