ralphctl: Skill for Claude Code

AI provider integration (Claude / Copilot / Codex / OpenCode / Grok)

Covers what is not in CLAUDE.md or .claude/docs/ARCHITECTURE.md. For harness signals, exit codes, sequential task execution, and check-script gating — see CLAUDE.md.

Source of truth:

• Provider adapters: src/integration/ai/providers/{claude,copilot,codex,opencode,grok}/ — one folder per tool, sibling-isolated. Each owns headless.ts, interactive.ts, and model-availability-probe.ts (Claude, Copilot, OpenCode, and Grok also have parse-stream.ts for stream-format handling). OpenCode is the aggregator backend: its model ids are provider/model and its catalog is discovered at runtime via opencode models, so its probe is the one that cannot check against a static list. Grok's probe is passthrough (not grok models).
• Shared engine: src/integration/ai/providers/_engine/ — spawn.ts (the ProviderSpawn port + default node:child_process.spawn impl), run-headless-spawn.ts (the headless wrapper that wires watchdog + signals file + sessionId file + rate-limit backoff), rate-limit-backoff.ts (exponential retry policy), idle-watchdog.ts (kills wedged children), headless-ai-provider.ts (the cross-tool port).
• Signal contract: src/integration/ai/contract/_engine/{validate-signals-file,render-sidecars,render-contract-section}.ts with per-kind Zod schemas under src/integration/ai/contract/_engine/signals/<kind>/schema.ts. Each AI-spawning leaf composes <leaf>.contract.ts from these primitives; the AI writes signals.json via its Write tool, the harness Zod-validates post-spawn.
• Composition: src/application/bootstrap/provider-factory.ts (createAiProvider) picks the concrete adapter from settings.ai.provider.

Spawn modes

There are two ports under _engine/:

import type { HeadlessAiProvider } from '@src/integration/ai/providers/_engine/headless-ai-provider.ts';
import type { InteractiveAiProvider } from '@src/integration/ai/providers/_engine/interactive-ai-provider.ts';