ralphctl

Cross-phase skill — question every piece of AI-workflow scaffolding on every model upgrade; remove non-load-bearing pieces one at a time with measurement. Complexity drifts upward by default; subtraction requires discipline. Governs scaffolding built around AI usage (prompts, wrapper scripts, guardrails, validation steps), not the task's application code — for code-level minimalism defer to the ralphctl-ponytail, ralphctl-surgical-simplicity, and ralphctl-karpathy-guidelines skills when installed in this session.

Model software around the business domain using bounded contexts, aggregates, and ubiquitous language. Use when the user mentions "domain modeling", "bounded context", "aggregate root", "ubiquitous language", "anti-corruption layer", "context mapping", "domain events", "strategic design", "the code doesnt match the business", or "how do we split this big system". Also trigger when breaking a monolith into services, defining service boundaries, or aligning code structure with business processes. Covers entities vs value objects, domain events, and context mapping strategies. For architecture layers, see clean-architecture. For complexity, see software-design-philosophy.

Refines raw ideas into sharp, actionable concepts through structured divergent and convergent thinking. Use when an idea is still vague, when you need to stress-test assumptions before committing to a plan, or when you want to expand options before converging on one. Triggers on "ideate", "refine this idea", or "stress-test my plan".

Cross-phase skill — establish a shared understanding of what will and will not be done before producing output: restate the input back to the user, surface assumptions, name non-goals, and agree before you write. For an input that is still a raw, unshaped idea needing multiple candidate directions before one is chosen, run the ralphctl-idea-refinement skill first when it is installed in this session; alignment then confirms whichever direction comes out of it.

Session-discipline skill — settle the plan before touching code, work in small verified increments with a feedback loop that proves each change works, and record corrections so the same mistake is not repeated. Use when executing multi-step coding tasks where batching unverified work would compound risk; bundles plan-first sequencing and learning capture on top of the narrower per-change habits in ralphctl-iterative-review and (when installed) ralphctl-karpathy-guidelines.

Behavioural guardrails against four empirical LLM coding failure modes — silent assumptions, over-complication, orthogonal damage to code you don't fully understand, and declaring done without verification. Use when writing, reviewing, or refactoring code to surface assumptions early, keep changes proportionate to the task, and loop until explicit success criteria pass; broader than the implementation-choice ladder in ralphctl-ponytail or the scope checklist in ralphctl-surgical-simplicity (when those are installed), which it complements rather than duplicates.

Anti-over-engineering ladder for choosing HOW to implement something — before writing custom code, climb the rungs in order and stop at the first that holds. Does this need to exist at all (YAGNI) → already in the codebase → standard library → native platform feature → already-installed dependency → one line → minimum code that works. Use when picking an implementation approach or evaluating a new dependency; for keeping the footprint of an already-chosen approach small, defer to the ralphctl-surgical-simplicity skill when installed.

Execute-phase scope-containment checklist — write the minimum code the task needs and touch only the files and lines the task requires; surface out-of-scope findings as notes rather than fixing them inline. Governs the footprint of a change whose approach is already decided; for choosing that implementation approach itself, defer to the ralphctl-ponytail skill when installed.

Systematic root-cause debugging. Use when tests fail, builds break, or behaviour does not match expectations. Follow stop-the-line → reproduce → localize → reduce → root-cause → guard-with-regression-test → verify, not guessing; the reproduction and regression steps follow the same red-green discipline as ralphctl-test-driven-development.

Domain-modelling skill — align code with the business domain through ubiquitous language, bounded contexts, small aggregates, domain events, and core-domain focus. Use when naming concepts, drawing module or service boundaries, deciding entity vs value object, integrating external systems, or when the code no longer matches how the business talks about itself.

Ideation skill — refine a raw, unshaped idea into a sharp, buildable concept through divergent expansion (variation lenses like inversion, simplification, audience shift) followed by convergent stress-testing (user value, feasibility, differentiation), ending in a one-pager with explicit assumptions and a "Not Doing" list. Use when an idea is still vague and multiple directions should be widened before narrowing; once a direction is already concrete, confirming it is the shorter restate-and-agree pass in ralphctl-alignment, not a full ideation cycle.

Cross-phase skill — treat AI output as a controlled feedback loop, not a one-shot generation. Run the cheap check after each meaningful change; re-read your own output before signalling completion. For the fuller session workflow — plan-first sequencing plus durable learning capture — see the opt-in ralphctl-cherny-workflow skill.

Execute-phase skill — write the failing test before the code that makes it pass; for bug fixes, this is the reproduction test itself. Use for any logic change, bug fix, or behavioural modification; for the full root-cause triage pipeline around an unexpected failure, see ralphctl-debugging-and-error-recovery.

Low-level AI CLI spawn mechanics used by ralphctl's provider adapters — headless / interactive spawn, the file-based contract (`signals.json` + `sessionId` files), idle-stdout watchdog, exponential rate-limit backoff, and `--resume` for in-flight recovery. Use when modifying `src/integration/ai/providers/{claude,copilot,codex}/` or `src/integration/ai/providers/_engine/`, debugging stdin hangs / slow Claude startups, or wiring a new code path that spawns an AI CLI directly.

Audit the ralphctl `.claude/` setup (the 7 subagents, the in-repo skills, the `.claude/docs/` modules) and `CLAUDE.md` for DRIFT against the real `src/` — stale version stamps, renamed/dead paths, removed symbols, unshipped env vars, and fabricated references. Use this whenever someone asks to "audit / refresh / clean up / check the .claude setup", before cutting a release, after a large rename or refactor under `src/`, or when an agent or doc cites a path/symbol that "feels off". This is doc/config drift — it complements `verify` (which runs typecheck/lint/test for code correctness); reach for drift-sweep when the question is "do our agent and doc files still describe the code as it actually is?".

Run the project's full verification gate — typecheck, lint, tests — in one go. Use after any code change before committing, or when the user asks "is it green?" / "can I ship this?" / "verify" / "run checks".

Article-grounded reference for the three Anthropic harness articles. Use when designing or auditing an agent harness, reasoning about long-running-agent state / memory / progress handoff, deciding how much scaffolding a flow needs, pruning components on a model bump, or designing a generator / evaluator split. The fuller "why" behind the `harness-principles` trigger and `.claude/docs/HARNESS-PRINCIPLES.md` status map.

Draft the ralphctl `CHANGELOG.md` `## [Unreleased]` section from the commits since the last release tag — grouping conventional-commit subjects into Keep-a-Changelog sections (Breaking / Added / Changed / Fixed / Removed) and flagging internal churn to omit. Use this whenever you're updating the changelog, preparing release notes, about to cut a release, or someone asks "what changed since the last version / tag". It produces a curated starting point, not a finished changelog — the changelog is user-facing prose, so the draft is meant to be rewritten for readers, not pasted raw.

Check the chain-flow step-traces documented in `.claude/docs/` (KERNEL-DESIGN.md examples, the `diagrams/`, REQUIREMENTS step lists) against the REAL element-name sequence each flow runs, and fix the drift. Use this after changing a flow's element list (adding/removing/reordering a `leaf`/`sequential`/`guard`/`loop`, renaming an element), before a release, or whenever a documented "this flow runs A → B → C" sequence feels stale. Flow definitions and their step-order fence tests are the source of truth; the prose traces in docs paraphrase them and rot silently. This is the step-order counterpart to `drift-sweep` (which handles path/version/symbol drift).

Cut a new release of ralphctl — bumps `package.json`, promotes the `## [Unreleased]` CHANGELOG section to a dated `## [X.Y.Z]`, opens a `chore(release): X.Y.Z` PR, defers to `merge-pr` to wait for CI and merge with admin bypass, then tags the merge commit and pushes the tag (which fires the `release.yml` workflow → npm publish + GitHub Release). Use when the user says "/release X.Y.Z", "release X.Y.Z", "ship 1.2.3", "cut a new version", or otherwise asks to publish a new version of ralphctl.

Multi-phase code-quality skill — primary frame for the evaluator role in Execute, the architecture axis in Plan, and correctness/readability in Refine. Multi-axis code review with severity vocabulary. Use when you are the evaluator assessing a generator's output, and when reviewing any change before signalling completion. AI-written code needs MORE scrutiny, not less.

Guides systematic root-cause debugging. Use when tests fail, builds break, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need a systematic approach to finding and fixing the root cause rather than guessing.

Drives development with tests. Use when implementing any logic, fixing any bug, or changing any behavior. Use when you need to prove that code works, when a bug report arrives, or when you're about to modify existing functionality.

Land an open PR on this repo — wait for CI to finish, then merge with a merge commit using admin bypass. Use whenever the user says "merge this PR", "/merge-pr", "ship the PR", "land the PR", or asks to merge a specific PR number. Defaults to the PR opened from the current branch.

Cross-phase skill — design the shape of the change (entities, boundaries, seams) before generating code, tasks, or acceptance criteria. Failure mode is "big blob" output that obscures the core change.

Auto-triggers on structural harness decisions: new chain primitive, new flow, remove evaluator, wrap evaluator, redesign harness, scaffolding, load-bearing, model upgrade, harness audit, refactor flow, sub-agent. Also triggers on file mentions of `src/application/chain/`, `src/application/flows/`, `src/integration/ai/providers/_engine/`. Instructs the agent to read the principles doc before proceeding.