--- title: "Requirements Clarification" description: "**Answer:** Include hook points across the full orchestrator lifecycle, wherever they provide value for management and observability." type: skill canonical_url: https://claudary.paisolsolutions.com/skills/requirements source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:46:04.709Z license: CC-BY-4.0 attribution: "Requirements Clarification — Claudary (https://claudary.paisolsolutions.com/skills/requirements)" --- # Requirements Clarification **Answer:** Include hook points across the full orchestrator lifecycle, wherever they provide value for management and observability. ## Overview # Requirements Clarification ## Q1 **Question:** Which orchestrator lifecycle phases do you want hook points for (for example: loop start/end, iteration start/end, task selection, plan creation, pre/post backpressure checks, merge queue events, human interaction events)? **Answer:** Include hook points across the full orchestrator lifecycle, wherever they provide value for management and observability. ## Q2 **Question:** Who should consume these hooks first, and through what mechanism (e.g., structured events to diagnostics JSONL, internal Rust callbacks/trait, external command/webhook integration, or all of the above)? **Answer:** Hooks should be a foundational mechanism to build on, similar to hook systems in Cloud Code and other agent harnesses. ## Q3 **Question:** For the first version, should hook handlers run as external executables/commands (like git hooks), in-process Rust plugins, or both? **Answer:** v1 should support user-configured hooks in YAML (project config and possibly global Ralph config), where users attach scripts/commands to lifecycle events, similar to Cloud Code-style hooks. ## Q4 **Question:** Should hook definitions support both scopes in v1 — (a) global/default hooks for all runs and (b) per-project hooks that can override or extend global ones? **Answer:** v1 should be per-project only. Global/default hook scope will be a separate future feature. ## Q5 **Question:** What should happen if a hook fails (non-zero exit, timeout, invalid output): fail the lifecycle step, warn and continue, or configurable per hook? **Answer:** Behavior should be configurable per hook. ## Q6 **Question:** Should hooks be allowed to block orchestration (synchronous pre-hooks), or should v1 be non-blocking/observability-only? **Answer:** Hooks should be able to block or at least suspend orchestration. ## Q7 **Question:** Do you want each hook invocation to receive a structured JSON payload on stdin (event name, run/loop IDs, iteration, timestamps, context), or should v1 pass only env vars/CLI args? **Answer:** Use structured JSON on stdin as the primary contract, plus minimal convenience env vars. ## Q8 **Question:** Which initial lifecycle events are mandatory for v1 (pick a minimal but useful set)? **Answer:** Include all events from the proposed starter set except backpressure events (exclude both `backpressure.passed` and `backpressure.failed`). ## Q9 **Question:** Should hooks be split into explicit `pre.` and `post.` phases for the same lifecycle point (so users can run guards before and notifications after)? **Answer:** Yes, include explicit `pre.` and `post.` phases. ## Q10 **Question:** If multiple hooks are configured for the same event phase, should they run in declaration order (sequential), in parallel, or configurable? **Answer:** Run sequentially in declaration order in v1 to minimize surprises. ## Q11 **Question:** Should v1 include built-in safeguards per hook (e.g., timeout_seconds, max_output_bytes, redaction of sensitive fields) with defaults? **Answer:** Include `timeout_seconds` and `max_output_bytes` safeguards in v1. ## Q12 **Question:** For observability, what should Ralph persist for each hook run (minimum set): start/end time, duration, exit code, timed_out flag, stdout/stderr (truncated), and associated lifecycle event? **Answer:** Yes—start with that telemetry set. ## Q13 **Question:** You said hooks may block or suspend orchestration. In v1, should “suspend” mean pause and wait for an explicit human/operator resume signal, or just delayed retry/backoff of the same step? **Answer:** Support a combination in v1: `wait_for_resume`, `retry_backoff`, and hybrid `wait_then_retry`. Default should be `wait_for_resume`. ## Q14 **Question:** For operator resume, what is the first control surface in v1: a new CLI command (e.g., `ralph loops resume `), a file signal, web API action, Telegram command, or multiple? **Answer:** Add a new CLI command: `ralph loops resume `. ## Q15 **Question:** Should hooks be able to mutate execution context in v1 (e.g., return JSON to modify prompt/events/config), or be side-effect-only with pass/fail/suspend decisions? **Answer:** Yes, allow mutation in v1, but only as explicit opt-in. It must be clearly called out and user-configured/acknowledged; default behavior should not mutate context. ## Q16 **Question:** What mutation surface should v1 allow initially (to keep risk bounded): add structured metadata only, inject additional prompt guidance, enqueue extra events, or full config mutation? **Answer:** Keep v1 simple: allow only structured metadata injection (no prompt/event/config mutation). ## Q17 **Question:** For that metadata contract, should v1 support JSON only (recommended for consistency with stdin payload), or both JSON and XML? **Answer:** JSON only in v1. ## Q18 **Question:** Should v1 include a dry-run/validation command (e.g., `ralph hooks validate`) to catch misconfigured hook commands and schemas before starting a loop? **Answer:** Yes. Add a validation command and reuse it in pre-flight checks. ## Q19 **Question:** What are your primary success criteria for this feature (top 3): e.g., reliable event coverage, low performance overhead, clear failure semantics, easy config UX, and testability? **Answer:** Extensibility, easy config UX, and strong testability. ## Q20 **Question:** Are there any explicit non-goals for v1 we should lock now (e.g., global hooks, parallel hook execution, remote/webhook destinations, XML output, full context mutation)? **Answer:** Yes—lock these as v1 non-goals: global hooks, parallel hook execution, XML output, and full prompt/event/config mutation. ## Q21 **Question:** Do we need a dedicated `task.selected` or `hat.selected` lifecycle hook event in v1? **Answer:** No. Remove dedicated `task.selected`/`hat.selected` events in v1 to avoid overlap/confusion. Use `iteration.start` payload to carry selected hat/task context instead. --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/requirements) · https://claudary.paisolsolutions.com