Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

hns-workflow-ci-loop

Unified CI watch + auto-fix loop skill. Polls gh pr checks after /moai sync PR creation, classifies required vs auxiliary failures, attempts safe automated patches (max 3 iterations), and escalates semantic failures to the user. Use for CI loop workflow — NOT for general loop iteration patterns (see moai-workflow-loop).

modu-ai · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add modu-ai/moai-adk --skill hns-workflow-ci-loop

About this skill


name: hns-workflow-ci-loop description: > Unified CI watch + auto-fix loop skill. Polls gh pr checks after /moai sync PR creation, classifies required vs auxiliary failures, attempts safe automated patches (max 3 iterations), and escalates semantic failures to the user. Use for CI loop workflow — NOT for general loop iteration patterns (see moai-workflow-loop).

when_to_use: > Use for the CI watch and auto-fix loop after /moai sync PR creation: polling gh pr checks, classifying required vs auxiliary failures, safe automated patch attempts (max 3 iterations), and escalation of semantic failures.

license: Apache-2.0 compatibility: Designed for Claude Code allowed-tools: Bash, Read user-invocable: false metadata: version: "0.1.0" category: "workflow" status: "active" updated: "2026-05-22" tags: "ci, watch, autofix, polling, github-actions, required-checks, force-push-prohibited"

progressive_disclosure: enabled: true level1_tokens: 120 level2_tokens: 5000

CI Loop (hns-workflow-ci-loop)

Unified CI watch + auto-fix loop. The orchestrator invokes this skill after /moai sync Phase 4 (gh pr create) returns a PR number. The skill polls required checks, classifies failures into mechanical vs semantic, attempts safe patches up to 3 iterations, and escalates semantic failures via AskUserQuestion.

Quick Reference

Trigger: /moai sync Phase 4 PR-create returns a PR number, or an existing PR needs CI monitoring.

Two phases, one skill:

  1. Watch — Poll gh pr checks every 30s, classify required vs auxiliary via .github/required-checks.yml SSoT; exit on green/fail/timeout.
  2. Auto-fix — On required-fail (exit 2), receive JSON handoff, run up to 3 patch iterations, escalate semantic failures immediately.

One-liner:

MOAI_CIWATCH_GH=gh sh scripts/ci-watch/run.sh <PR_NUMBER> <BRANCH>

Exit codes:

  • 0 — all required passed → ready-to-merge AskUserQuestion
  • 1 — fatal error → surface remediation
  • 2 — required failure → JSON handoff → auto-fix phase
  • 3 — 30-min hard timeout → blocker message, return control

HARD invariants:

  • AskUserQuestion is orchestrator-only — CLI, shell scripts, and the manager-develop (cycle_type=autofix) subagent MUST NOT call it.
  • Force-push is absolutely prohibited (--force, -f, --force-with-lease all banned).
  • Max 3 auto-fix iterations; iteration 4+ triggers mandatory blocking AskUserQuestion.
  • Semantic failures (race, deadlock, panic, assertion) are never auto-patched.
  • Protected files: .env*, credentials, .claude/settings*.json, .github/required-checks.yml, scripts/ci-watch/run.sh.

Implementation Guide

Phase 1 — Watch Loop

Polling cadence: 30 seconds minimum (GitHub API rate-limit). Override via CIWATCH_POLL_INTERVAL env, never below 30 in production. Test mode uses MOAI_CIWATCH_NO_SLEEP=1 (single-tick exit).

30-minute hard timeout: CIWATCH_TIMEOUT_SECONDS=1800 default. On timeout, exit 3. Do not auto-restart.

Required vs auxiliary: Required checks live in .github/required-checks.yml branches.<pattern>.contexts. Auxiliary checks listed under auxiliary: MUST NOT block ready-to-merge. Hardcoding check names in scripts is prohibited.

State file: .moai/state/ci-watch-active.flag (YAML). Tracks pr_number, started_at, heartbeat_at, required_checks, abort_requested. Heartbeat staleness > 90s allows takeover. Abort: moai pr watch --abort.

Background watch standardization: For long-running PRs (5+ min), use gh pr checks <PR> --watch invoked via run_in_background: true. Sleep + poll loops are prohibited — they block the orchestrator's main session.

Status report format (stderr, state-change ticks only, no ANSI):

[ci-watch] PR #<N>: required 4/6 pass, 2 pending; advisory 0 fail

Handoff schema on exit 2 — JSON with stable fields: prNumber, branch, failedChecks[] (each entry {name, runId, logUrl}), auxiliaryFailCount, totalRequired. Field stability: name, runId, logUrl are stable contract — do not rename. Schema source: the CI-watch handoff struct.

Phase 2 — Auto-Fix Loop

Entry condition: ci-watch exit 2 + valid JSON handoff. State file: .moai/state/ci-autofix-<PR>.json (PR-scoped, 24-hour staleness threshold).

OQ2 cadence matrix (single source of truth for iteration behavior):

  • iter 1, any mechanical sub_class → confirm + apply via AskUserQuestion (1st option = "Apply patch (Recommended)").
  • iter 1, semantic/unknown → escalate (no patch attempt) via AskUserQuestion with diagnosis report.
  • iter 2-3, mechanical + sub_class=trivial → silent apply + log (no AskUserQuestion).
  • iter 2-3, mechanical + sub_class=non-trivial → confirm + apply via AskUserQuestion.
  • iter 2-3, semantic/unknown → escalate (no patch) via AskUserQuestion.
  • iter 4+ → mandatory blocking AskUserQuestion (no timer, options: manual fix / revise SPEC / abandon PR).

"trivial" = whitespace, gofmt/goimports, import-order (matches classify.sh RX_TRIVIAL_*).

Patch commit rule: Every patch = new commit. Format: fix(ci): auto-fix <classification> failure (iter <N>). After push, re-invoke scripts/ci-watch/run.sh to restart the watch loop.

Iteration 4+ escalation (mandatory blocking, no silent timeout):

  1. (Recommended) Manual fix — investigate and fix manually
  2. Revise SPEC — revise the SPEC and restart implementation
  3. Abandon PR — close the PR and abandon this approach

manager-develop (cycle_type=autofix) spawn prompt injects: handoff JSON, classification + sub_class, failed CI log + PR diff, mode directive (mechanical → propose unified-diff patch; semantic/unknown → return diagnosis only, no patch). HARD: no AskUserQuestion call from the subagent — return Markdown only.

Audit log: .moai/logs/ci-autofix/<PR-NNN>-<YYYY-MM-DD>.md. Append-only. Each iteration records classification, sub_class, action, patch_sha, escalation_reason.

Pro

Read the complete source ↗