@jstn-sdk/rcs 0.1.0

package/plugins/roblox-ai-os-creator-skills/skills/pipeline/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: pipeline
+description: Configurable pipeline orchestrator for sequencing stages
+---
+
+# Pipeline Skill
+
+`$pipeline` is the configurable pipeline orchestrator for RCS. It sequences stages
+through a uniform `PipelineStage` interface, with state persistence and resume support.
+
+## Default Autopilot Pipeline
+
+The canonical RCS pipeline sequences:
+
+```
+RALPLAN (consensus planning) -> team-exec (Codex CLI workers) -> ralph-verify (architect verification)
+```
+
+## Configuration
+
+Pipeline parameters are configurable per run:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `maxRalphIterations` | 10 | Ralph verification iteration ceiling |
+| `workerCount` | 2 | Number of Codex CLI team workers |
+| `agentType` | `executor` | Agent type for team workers |
+
+## Stage Interface
+
+Every stage implements the `PipelineStage` interface:
+
+```typescript
+interface PipelineStage {
+  readonly name: string;
+  run(ctx: StageContext): Promise<StageResult>;
+  canSkip?(ctx: StageContext): boolean;
+}
+```
+
+Stages receive a `StageContext` with accumulated artifacts from prior stages and
+return a `StageResult` with status, artifacts, and duration.
+
+## Built-in Stages
+
+- **ralplan**: Consensus planning (planner + architect + critic). Skips only when both `prd-*.md` and `test-spec-*.md` planning artifacts already exist, and carries any `deep-interview-*.md` spec paths forward for traceability.
+- **team-exec**: Team execution via Codex CLI workers. Always the RCS execution backend.
+- **ralph-verify**: Ralph verification loop with configurable iteration count.
+
+## State Management
+
+Pipeline state persists via the ModeState system at `.rcs/state/pipeline-state.json`.
+The HUD renders pipeline phase automatically. Resume is supported from the last incomplete stage.
+
+- **On start**: `state_write({mode: "pipeline", active: true, current_phase: "stage:ralplan"})`
+- **On stage transitions**: `state_write({mode: "pipeline", current_phase: "stage:<name>"})`
+- **On completion**: `state_write({mode: "pipeline", active: false, current_phase: "complete"})`
+
+## API
+
+```typescript
+import {
+  runPipeline,
+  createAutopilotPipelineConfig,
+  createRalplanStage,
+  createTeamExecStage,
+  createRalphVerifyStage,
+} from './pipeline/index.js';
+
+const config = createAutopilotPipelineConfig('build feature X', {
+  stages: [
+    createRalplanStage(),
+    createTeamExecStage({ workerCount: 3, agentType: 'executor' }),
+    createRalphVerifyStage({ maxIterations: 15 }),
+  ],
+});
+
+const result = await runPipeline(config);
+```
+
+## Relationship to Other Modes
+
+- **autopilot**: Autopilot can use pipeline as its execution engine (v0.8+)
+- **team**: Pipeline delegates execution to team mode (Codex CLI workers)
+- **ralph**: Pipeline delegates verification to ralph (configurable iterations)
+- **ralplan**: Pipeline's first stage runs RALPLAN consensus planning

package/plugins/roblox-ai-os-creator-skills/skills/plan/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: plan
+description: Strategic planning with optional interview workflow
+---
+
+<Purpose>
+Plan creates comprehensive, actionable work plans through intelligent interaction. It auto-detects whether to interview the user (broad requests) or plan directly (detailed requests), and supports consensus mode (iterative Planner/Architect/Critic loop with RALPLAN-DR structured deliberation) and review mode (Critic evaluation of existing plans).
+</Purpose>
+
+<Use_When>
+- User wants to plan before implementing -- "plan this", "plan the", "let's plan"
+- User wants structured requirements gathering for a vague idea
+- User wants an existing plan reviewed -- "review this plan", `--review`
+- User wants multi-perspective consensus on a plan -- `--consensus`, "ralplan"
+- Task is broad or vague and needs scoping before any code is written
+</Use_When>
+
+<Do_Not_Use_When>
+- User wants autonomous end-to-end execution -- use `autopilot` instead
+- User wants to start coding immediately with a clear task -- use `ralph` or delegate to executor
+- User asks a simple question that can be answered directly -- just answer it
+- Task is a single focused fix with obvious scope -- skip planning, just do it
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Jumping into code without understanding requirements leads to rework, scope creep, and missed edge cases. Plan provides structured requirements gathering, expert analysis, and quality-gated plans so that execution starts from a solid foundation. The consensus mode adds multi-perspective validation for high-stakes projects.
+</Why_This_Exists>
+
+<Execution_Policy>
+- Auto-detect interview vs direct mode based on request specificity
+- Ask one question at a time during interviews -- never batch multiple interview rounds into one question form
+- Gather codebase facts via `explore` agent before asking the user about them
+- When session guidance enables `USE_RCS_EXPLORE_CMD`, prefer `rcs explore` for simple read-only repository lookups during planning; keep prompts narrow and concrete, and keep prompt-heavy or ambiguous planning work on the richer normal path and fall back normally if `rcs explore` is unavailable.
+- Plans must meet quality standards: 80%+ claims cite file/line, 90%+ criteria are testable
+- Implementation step count must be right-sized to task scope; avoid defaulting to exactly five steps when the work is clearly smaller or larger
+- Consensus mode outputs the final plan by default; add `--interactive` to enable execution handoff
+- Consensus mode uses RALPLAN-DR short mode by default; switch to deliberate mode with `--deliberate` or when the request explicitly signals high risk (auth/security, data migration, destructive/irreversible changes, production incident, compliance/PII, public API breakage)
+- Apply the shared workflow guidance pattern: outcome-first framing, concise visible updates for multi-step planning, local overrides for the active workflow branch, evidence-backed planning and validation expectations, explicit stop rules, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches.
+</Execution_Policy>
+
+<Steps>
+
+### Mode Selection
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Interview | Default for broad requests | Interactive requirements gathering |
+| Direct | `--direct`, or detailed request | Skip interview, generate plan directly |
+| Consensus | `--consensus`, "ralplan" | Planner -> Architect -> Critic loop until agreement with RALPLAN-DR structured deliberation (short by default, `--deliberate` for high-risk); outputs plan by default |
+| Consensus Interactive | `--consensus --interactive` | Same as Consensus but pauses for user feedback at draft and approval steps, then hands off to execution |
+| Review | `--review`, "review this plan" | Critic evaluation of existing plan |
+
+### Interview Mode (broad/vague requests)
+
+1. **Classify the request**: Broad (vague verbs, no specific files, touches 3+ areas) triggers interview mode
+2. **Ask one focused question** using the surface-appropriate structured question path for preferences, scope, and constraints: in attached-tmux RCS runtime use `rcs question`; outside tmux use native structured input when available; use plain text only as a last fallback
+3. **Gather codebase facts first**: Before asking "what patterns does your code use?", spawn an `explore` agent to find out, then ask informed follow-up questions
+4. **Build on answers**: Each question builds on the previous answer
+5. **Consult Analyst** (THOROUGH tier) for hidden requirements, edge cases, and risks
+6. **Create plan** when the user signals readiness: "create the plan", "I'm ready", "make it a work plan"
+
+### Direct Mode (detailed requests)
+
+1. **Quick Analysis**: Optional brief Analyst consultation
+2. **Create plan**: Generate comprehensive work plan immediately
+3. **Review** (optional): Critic review if requested
+
+### Consensus Mode (`--consensus` / "ralplan")
+
+**RALPLAN-DR modes**: **Short** (default, bounded structure) and **Deliberate** (for `--deliberate` or explicit high-risk requests). Both modes keep the same Planner -> Architect -> Critic sequence. The workflow auto-proceeds through planning steps (Planner/Architect/Critic) but outputs the final plan without executing.
+
+1. **Planner** creates initial plan and a compact **RALPLAN-DR summary** before any Architect review. The summary **MUST** include:
+   - **Principles** (3-5)
+   - **Decision Drivers** (top 3)
+   - **Viable Options** (>=2) with bounded pros/cons for each option
+   - If only one viable option remains, an explicit **invalidation rationale** for the alternatives that were rejected
+   - In **deliberate mode**: a **pre-mortem** (3 failure scenarios) and an **expanded test plan** covering **unit / integration / e2e / observability**
+2. **User feedback** *(--interactive only)*: If running with `--interactive`, **MUST** use `AskUserQuestion` / the structured question UI (`rcs question` in attached tmux; native structured input outside tmux when available) to present the draft plan **plus the RALPLAN-DR Principles / Decision Drivers / Options summary for early direction alignment** with these options:
+   - **Proceed to review** — send to Architect and Critic for evaluation
+   - **Request changes** — return to step 1 with user feedback incorporated
+   - **Skip review** — go directly to final approval (step 7)
+   If NOT running with `--interactive`, automatically proceed to review (step 3).
+3. **Architect** reviews for architectural soundness using `ask_codex` with `agent_role: "architect"`. Architect review **MUST** include: strongest steelman counterargument (antithesis) against the favored option, at least one meaningful tradeoff tension, and (when possible) a synthesis path. In deliberate mode, Architect should explicitly flag principle violations. **Wait for this step to complete before proceeding to step 4.** Do NOT run steps 3 and 4 in parallel.
+4. **Critic** evaluates against quality criteria using `ask_codex` with `agent_role: "critic"`. Critic **MUST** verify principle-option consistency, fair alternative exploration, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. Critic **MUST** explicitly reject shallow alternatives, driver contradictions, vague risks, or weak verification. In deliberate mode, Critic **MUST** reject missing/weak pre-mortem or missing/weak expanded test plan. Run only after step 3 is complete.
+5. **Re-review loop** (max 5 iterations): If Critic rejects or iterates, execute this closed loop:
+   a. Collect all feedback from Architect + Critic
+   b. Pass feedback to Planner to produce a revised plan
+   c. **Return to Step 3** — Architect reviews the revised plan
+   d. **Return to Step 4** — Critic evaluates the revised plan
+   e. Repeat until Critic approves OR max 5 iterations reached
+   f. If max iterations reached without approval, present the best version to user via the structured question UI with note that expert consensus was not reached
+6. **Apply improvements**: When reviewers approve with improvement suggestions, merge all accepted improvements into the plan file before proceeding. Final consensus output **MUST** include an **ADR** section with: **Decision**, **Drivers**, **Alternatives considered**, **Why chosen**, **Consequences**, **Follow-ups**. Specifically:
+   a. Collect all improvement suggestions from Architect and Critic responses
+   b. Deduplicate and categorize the suggestions
+   c. Update the plan file in `.rcs/plans/` with the accepted improvements (add missing details, refine steps, strengthen acceptance criteria, ADR updates, etc.)
+   d. Note which improvements were applied in a brief changelog section at the end of the plan
+   e. Before any execution handoff, derive an explicit **available-agent-types roster** from the known prompt catalog and add concrete **follow-up staffing guidance** for both `$ralph` and `$team` (recommended roles, counts, suggested reasoning levels by lane, and why each lane exists)
+   f. For the `$team` path, add an explicit launch-hint block with concrete `rcs team` / `$team` commands and a **team verification path** (what team proves before shutdown, what Ralph verifies after handoff)
+7. On Critic approval (with improvements applied): *(--interactive only)* If running with `--interactive`, use `AskUserQuestion` / the structured question UI to present the plan with these options:
+   - **Approve and execute** — proceed to implementation via ralph+ultrawork
+   - **Approve and implement via team** — proceed to implementation via coordinated parallel team agents
+   - **Request changes** — return to step 1 with user feedback
+   - **Reject** — discard the plan entirely
+   If NOT running with `--interactive`, output the final approved plan and stop. Do NOT auto-execute.
+8. *(--interactive only)* User chooses via the structured question UI (never ask for approval in plain text when a structured surface is available)
+9. On user approval (--interactive only):
+   - **Approve and execute**: **MUST** invoke `$ralph` with the approved plan path from `.rcs/plans/` as context **plus the explicit available-agent-types roster, suggested reasoning levels, concrete role allocation guidance, and direct launch hints for Ralph follow-up work**. Do NOT implement directly. Do NOT edit source code files in the planning agent. The ralph skill handles execution via ultrawork parallel agents.
+   - **Approve and implement via team**: **MUST** invoke `$team` with the approved plan path from `.rcs/plans/` as context **plus the explicit available-agent-types roster, suggested reasoning levels, concrete staffing / worker-role allocation guidance, explicit `rcs team` / `$team` launch hints, and the team verification path**. Do NOT implement directly. The team skill coordinates parallel agents across the staged pipeline for faster execution on large tasks.
+
+### Review Mode (`--review`)
+
+0. Treat review as a reviewer-only pass. The context that wrote the plan, cleanup proposal, or diff MUST NOT be the context that approves it.
+1. Read plan file from `.rcs/plans/`
+2. Evaluate via Critic using `ask_codex` with `agent_role: "critic"`
+3. For cleanup/refactor/anti-slop work, verify that the artifact includes a cleanup plan, regression tests or an explicit test gap, smell-by-smell passes, and quality gates.
+4. Return verdict: APPROVED, REVISE (with specific feedback), or REJECT (replanning required)
+5. If the current context authored the artifact, hand the review to `/review`, `critic`, `quality-reviewer`, `security-reviewer`, or `verifier` as appropriate.
+
+### Plan Output Format
+
+Every plan includes:
+- Requirements Summary
+- Acceptance Criteria (testable)
+- Implementation Steps (with file references)
+- Adaptive step count sized to the actual scope (not a fixed five-step template)
+- Risks and Mitigations
+- Verification Steps
+- For consensus/ralplan: **RALPLAN-DR summary** (Principles, Decision Drivers, Options)
+- For consensus/ralplan final output: **ADR** (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups)
+- For consensus/ralplan execution handoff: **Available-Agent-Types Roster**, **Follow-up Staffing Guidance** (including suggested reasoning levels by lane), explicit `rcs team` / `$team` **Launch Hints**, and **Team Verification Path**
+- For deliberate consensus mode: **Pre-mortem (3 scenarios)** and **Expanded Test Plan** (unit/integration/e2e/observability)
+
+Plans are saved to `.rcs/plans/`. Drafts go to `.rcs/drafts/`.
+</Steps>
+
+<Tool_Usage>
+- Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools
+- Use the surface-appropriate structured question path for preference questions (scope, priority, timeline, risk tolerance): attached-tmux RCS runtime uses `rcs question`; outside tmux uses native structured input when available. Use plain text only as a last fallback for unsupported surfaces or highly specific free-form values.
+- `rcs question` success JSON uses `answers[]` as the primary contract. For single-question planning prompts, read `answers[0].answer`; treat top-level `answer` as legacy compatibility fallback only.
+- Batch `questions[]` may be used for non-interview grouped preference or approval prompts when one submitted form is clearer than multiple interruptions; interview mode still asks one question per round.
+- Use the `explore` agent (LOW tier, bounded quick pass) to gather codebase facts before asking the user
+- Use `ask_codex` with `agent_role: "planner"` for planning validation on large-scope plans
+- Use `ask_codex` with `agent_role: "analyst"` for requirements analysis
+- Use `ask_codex` with `agent_role: "critic"` for plan review in consensus and review modes
+- If ToolSearch finds no MCP tools or Codex is unavailable, fall back to equivalent RCS prompt agents -- never block on external tools
+- **CRITICAL — Consensus mode agent calls MUST be sequential, never parallel.** Always await the Architect result before issuing the Critic call.
+- In consensus mode, default to RALPLAN-DR short mode; enable deliberate mode on `--deliberate` or explicit high-risk signals (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage)
+- In consensus mode with `--interactive`: use `AskUserQuestion` / the structured question UI for the user feedback step (step 2) and the final approval step (step 7) -- never ask for approval in plain text when a structured surface is available. Without `--interactive`, auto-proceed through planning steps without pausing. Output the final plan without execution.
+- In consensus mode with `--interactive`, on user approval **MUST** invoke `$ralph` for execution (step 9) -- never implement directly in the planning agent
+- In consensus mode, execution follow-up handoff **MUST** include an explicit available-agent-types roster plus concrete staffing / role-allocation guidance grounded in that roster, suggested reasoning levels by lane, explicit `rcs team` / `$team` launch hints, and a team verification path
+</Tool_Usage>
+
+
+## Scenario Examples
+
+**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.
+
+**Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
+
+**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
+
+<Examples>
+<Good>
+Adaptive interview (gathering facts before asking):
+```
+Planner: [spawns explore agent: "find authentication implementation"]
+Planner: [receives: "Auth is in src/auth/ using JWT with passport.js"]
+Planner: "I see you're using JWT authentication with passport.js in src/auth/.
+         For this new feature, should we extend the existing auth or add a separate auth flow?"
+```
+Why good: Answers its own codebase question first, then asks an informed preference question.
+</Good>
+
+<Good>
+Single question at a time:
+```
+Q1: "What's the main goal?"
+A1: "Improve performance"
+Q2: "For performance, what matters more -- latency or throughput?"
+A2: "Latency"
+Q3: "For latency, are we optimizing for p50 or p99?"
+```
+Why good: Each question builds on the previous answer. Focused and progressive.
+</Good>
+
+<Bad>
+Asking about things you could look up:
+```
+Planner: "Where is authentication implemented in your codebase?"
+User: "Uh, somewhere in src/auth I think?"
+```
+Why bad: The planner should spawn an explore agent to find this, not ask the user.
+</Bad>
+
+<Bad>
+Batching multiple questions:
+```
+"What's the scope? And the timeline? And who's the audience?"
+```
+Why bad: Three questions at once causes shallow answers. Ask one at a time.
+</Bad>
+
+<Bad>
+Presenting all design options at once:
+```
+"Here are 4 approaches: Option A... Option B... Option C... Option D... Which do you prefer?"
+```
+Why bad: Decision fatigue. Present one option with trade-offs, get reaction, then present the next.
+</Bad>
+</Examples>
+
+<Escalation_And_Stop_Conditions>
+- Stop interviewing when requirements are clear enough to plan -- do not over-interview
+- In consensus mode, stop after 5 Planner/Architect/Critic iterations and present the best version
+- Consensus mode outputs the plan by default; with `--interactive`, user can approve and hand off to ralph/team
+- If the user says "just do it" or "skip planning", **MUST** invoke `$ralph` to transition to execution mode. Do NOT implement directly in the planning agent.
+- Escalate to the user when there are irreconcilable trade-offs that require a business decision
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] Plan has testable acceptance criteria (90%+ concrete)
+- [ ] Plan references specific files/lines where applicable (80%+ claims)
+- [ ] All risks have mitigations identified
+- [ ] No vague terms without metrics ("fast" -> "p99 < 200ms")
+- [ ] Plan saved to `.rcs/plans/`
+- [ ] In consensus mode: RALPLAN-DR summary includes 3-5 principles, top 3 drivers, and >=2 viable options (or explicit invalidation rationale)
+- [ ] In consensus mode final output: ADR section included (Decision / Drivers / Alternatives considered / Why chosen / Consequences / Follow-ups)
+- [ ] In deliberate consensus mode: pre-mortem (3 scenarios) + expanded test plan (unit/integration/e2e/observability) included
+- [ ] In consensus mode with `--interactive`: user explicitly approved before any execution; without `--interactive`: output final plan after Critic approval (no auto-execution)
+</Final_Checklist>
+
+<Advanced>
+## Design Option Presentation
+
+When presenting design choices during interviews, chunk them:
+
+1. **Overview** (2-3 sentences)
+2. **Option A** with trade-offs
+3. [Wait for user reaction]
+4. **Option B** with trade-offs
+5. [Wait for user reaction]
+6. **Recommendation** (only after options discussed)
+
+Format for each option:
+```
+### Option A: [Name]
+**Approach:** [1 sentence]
+**Pros:** [bullets]
+**Cons:** [bullets]
+
+What's your reaction to this approach?
+```
+
+## Question Classification
+
+Before asking any interview question, classify it:
+
+| Type | Examples | Action |
+|------|----------|--------|
+| Codebase Fact | "What patterns exist?", "Where is X?" | Explore first, do not ask user |
+| User Preference | "Priority?", "Timeline?" | Ask user via the structured question path (`rcs question` in attached tmux; native structured input where available) |
+| Scope Decision | "Include feature Y?" | Ask user |
+| Requirement | "Performance constraints?" | Ask user |
+
+## Review Quality Criteria
+
+| Criterion | Standard |
+|-----------|----------|
+| Clarity | 80%+ claims cite file/line |
+| Testability | 90%+ criteria are concrete |
+| Verification | All file refs exist |
+| Specificity | No vague terms |
+
+## Deprecation Notice
+
+The separate `/planner`, `/ralplan`, and `/review` skills have been merged into `$plan`. All workflows (interview, direct, consensus, review) are available through `$plan`.
+</Advanced>

package/plugins/roblox-ai-os-creator-skills/skills/ralph/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: ralph
+description: Self-referential loop until task completion with architect verification
+---
+
+[RALPH + ULTRAWORK - ITERATION {{ITERATION}}/{{MAX}}]
+
+Your previous attempt did not output the completion promise. Continue working on the task.
+
+<Purpose>
+Ralph is a persistence loop that keeps working on a task until it is fully complete and architect-verified. It wraps ultrawork's parallel execution with session persistence, automatic retry on failure, and mandatory verification before completion.
+</Purpose>
+
+<Use_When>
+- Task requires guaranteed completion with verification (not just "do your best")
+- User says "ralph", "don't stop", "must complete", "finish this", or "keep going until done"
+- Work may span multiple iterations and needs persistence across retries
+- Task benefits from parallel execution with architect sign-off at the end
+</Use_When>
+
+<Do_Not_Use_When>
+- User wants a full autonomous pipeline from idea to code -- use `autopilot` instead
+- User wants to explore or plan before committing -- use `plan` skill instead
+- User wants a quick one-shot fix -- delegate directly to an executor agent
+- User wants manual control over completion -- use `ultrawork` directly
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Complex tasks often fail silently: partial implementations get declared "done", tests get skipped, edge cases get forgotten. Ralph prevents this by looping until work is genuinely complete, requiring fresh verification evidence before allowing completion, and using tiered architect review to confirm quality.
+</Why_This_Exists>
+
+<Execution_Policy>
+- Fire independent agent calls simultaneously -- never wait sequentially for independent work
+- Use `run_in_background: true` for long operations (installs, builds, test suites)
+- Always pass the `model` parameter explicitly when delegating to agents
+- Read `docs/shared/agent-tiers.md` before first delegation to select correct agent tiers
+- Deliver the full implementation: no scope reduction, no partial completion, no deleting tests to make them pass
+- Apply the shared workflow guidance pattern: outcome-first framing, concise visible updates for multi-step execution, local overrides for the active workflow branch, validation proportional to risk, explicit stop rules, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches.
+</Execution_Policy>
+
+<Steps>
+0. **Pre-context intake (required before planning/execution loop starts)**:
+   - Assemble or load a context snapshot at `.rcs/context/{task-slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`).
+   - Minimum snapshot fields:
+     - task statement
+     - desired outcome
+     - known facts/evidence
+     - constraints
+     - unknowns/open questions
+     - likely codebase touchpoints
+   - If an existing relevant snapshot is available, reuse it and record the path in Ralph state.
+   - If request ambiguity is high, gather brownfield facts first. When session guidance enables `USE_RCS_EXPLORE_CMD`, prefer `rcs explore` for simple read-only repository lookups with narrow, concrete prompts; otherwise use the richer normal explore path. Then run `$deep-interview --quick <task>` to close critical gaps.
+   - Do not begin Ralph execution work (delegation, implementation, or verification loops) until snapshot grounding exists. If forced to proceed quickly, note explicit risk tradeoffs.
+1. **Review progress**: Check TODO list and any prior iteration state
+2. **Continue from where you left off**: Pick up incomplete tasks
+3. **Delegate in parallel**: Route tasks to specialist agents at appropriate tiers
+   - Simple lookups: LOW tier -- "What does this function return?"
+   - Standard work: STANDARD tier -- "Add error handling to this module"
+   - Complex analysis: THOROUGH tier -- "Debug this race condition"
+   - When Ralph is entered as a ralplan follow-up, start from the approved **available-agent-types roster** and make the delegation plan explicit: implementation lane, evidence/regression lane, and final sign-off lane using only known agent types
+4. **Run long operations in background**: Builds, installs, test suites use `run_in_background: true`
+5. **Visual task gate (when screenshot/reference images are present)**:
+   - Run `$visual-verdict` **before every next edit**.
+   - Require structured JSON output: `score`, `verdict`, `category_match`, `differences[]`, `suggestions[]`, `reasoning`.
+   - Persist verdict to `.rcs/state/{scope}/ralph-progress.json` including numeric + qualitative feedback.
+   - Default pass threshold: `score >= 90`.
+   - **URL-based visual cloning tasks**: When the task description contains a target URL (e.g., "clone https://example.com"), route the work through `$visual-ralph`. `$web-clone` is hard-deprecated; Visual Ralph owns the migrated live-URL visual implementation use case and uses `$visual-verdict` for measured visual scoring.
+6. **Verify completion with fresh evidence**:
+   a. Identify what command proves the task is complete
+   b. Run verification (test, build, lint)
+   c. Read the output -- confirm it actually passed
+   d. Check: zero pending/in_progress TODO items
+7. **Architect verification** (tiered):
+   - <5 files, <100 lines with full tests: STANDARD tier minimum (architect role)
+   - Standard changes: STANDARD tier (architect role)
+   - >20 files or security/architectural changes: THOROUGH tier (architect role)
+   - Ralph floor: always at least STANDARD, even for small changes
+7.5 **Mandatory Deslop Pass**:
+   - After Step 7 passes, run `roblox-ai-os-creator-skills:ai-slop-cleaner` on **all files changed during the Ralph session**.
+   - Scope the cleaner to **changed files only**; do not widen the pass beyond Ralph-owned edits.
+   - Run the cleaner in **standard mode** (not `--review`).
+   - If the prompt contains `--no-deslop`, skip Step 7.5 entirely and proceed with the most recent successful verification evidence.
+7.6 **Regression Re-verification**:
+   - After the deslop pass, re-run all tests/build/lint and read the output to confirm they still pass.
+   - If post-deslop regression fails, roll back cleaner changes or fix and retry. Then rerun Step 7.5 and Step 7.6 until the regression is green.
+   - Do not proceed to completion until post-deslop regression is green (unless `--no-deslop` explicitly skipped the deslop pass).
+8. **On approval**: Run `/cancel` to cleanly exit and clean up all state files
+9. **On rejection**: Fix the issues raised, then re-verify at the same tier
+</Steps>
+
+<Tool_Usage>
+- Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools
+- Use `ask_codex` with `agent_role: "architect"` for verification cross-checks when changes are security-sensitive, architectural, or involve complex multi-system integration
+- Skip Codex consultation for simple feature additions, well-tested changes, or time-critical verification
+- If ToolSearch finds no MCP tools or Codex is unavailable, proceed with architect agent verification alone -- never block on external tools
+- Use `state_write` / `state_read` for ralph mode state persistence between iterations
+- Persist context snapshot path in Ralph mode state so later phases and agents share the same grounding context
+- If an `rcs_state` MCP tool call reports that its stdio transport is unavailable/closed, do **not** retry the same MCP call. Retry once through the supported CLI parity surface with the same payload, preserving `workingDirectory` and `session_id`: `rcs state write --input '<json>' --json`, `rcs state read --input '<json>' --json`, or `rcs state clear --input '<json>' --json`. If the CLI path also fails, continue with `.rcs/context` / `.rcs/plans` file-backed artifacts and report the state persistence blocker.
+</Tool_Usage>
+
+## State Management
+
+Use the `rcs_state` MCP server tools (`state_write`, `state_read`, `state_clear`) for Ralph lifecycle state.
+
+- **On start**:
+  `state_write({mode: "ralph", active: true, iteration: 1, max_iterations: 10, current_phase: "executing", started_at: "<now>", state: {context_snapshot_path: "<snapshot-path>"}})`
+- **On each iteration**:
+  `state_write({mode: "ralph", iteration: <current>, current_phase: "executing"})`
+- **On verification/fix transition**:
+  `state_write({mode: "ralph", current_phase: "verifying"})` or `state_write({mode: "ralph", current_phase: "fixing"})`
+- **On completion**:
+  `state_write({mode: "ralph", active: false, current_phase: "complete", completed_at: "<now>"})`
+- **On cancellation/cleanup**:
+  run `$cancel` (which should call `state_clear(mode="ralph")`)
+
+
+## Scenario Examples
+
+**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.
+
+**Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
+
+**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
+
+<Examples>
+<Good>
+Correct parallel delegation:
+```
+delegate(role="executor", tier="LOW", task="Add type export for UserConfig")
+delegate(role="executor", tier="STANDARD", task="Implement the caching layer for API responses")
+delegate(role="executor", tier="THOROUGH", task="Refactor auth module to support OAuth2 flow")
+```
+Why good: Three independent tasks fired simultaneously at appropriate tiers.
+</Good>
+
+<Good>
+Correct verification before completion:
+```
+1. Run: npm test           → Output: "42 passed, 0 failed"
+2. Run: npm run build      → Output: "Build succeeded"
+3. Run: lsp_diagnostics    → Output: 0 errors
+4. Delegate to architect at STANDARD tier  → Verdict: "APPROVED"
+5. Run /cancel
+```
+Why good: Fresh evidence at each step, architect verification, then clean exit.
+</Good>
+
+<Bad>
+Claiming completion without verification:
+"All the changes look good, the implementation should work correctly. Task complete."
+Why bad: Uses "should" and "look good" -- no fresh test/build output, no architect verification.
+</Bad>
+
+<Bad>
+Sequential execution of independent tasks:
+```
+delegate(executor, LOW, "Add type export") → wait →
+delegate(executor, STANDARD, "Implement caching") → wait →
+delegate(executor, THOROUGH, "Refactor auth")
+```
+Why bad: These are independent tasks that should run in parallel, not sequentially.
+</Bad>
+</Examples>
+
+<Escalation_And_Stop_Conditions>
+- Stop and report when a fundamental blocker requires user input (missing credentials, unclear requirements, external service down)
+- Stop when the user says "stop", "cancel", or "abort" -- run `/cancel`
+- Continue working when the hook system sends "The boulder never stops" -- this means the iteration continues
+- If architect rejects verification, fix the issues and re-verify (do not stop)
+- If the same issue recurs across 3+ iterations, report it as a potential fundamental problem
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] All requirements from the original task are met (no scope reduction)
+- [ ] Zero pending or in_progress TODO items
+- [ ] Fresh test run output shows all tests pass
+- [ ] Fresh build output shows success
+- [ ] lsp_diagnostics shows 0 errors on affected files
+- [ ] Architect verification passed (STANDARD tier minimum)
+- [ ] ai-slop-cleaner pass completed on changed files (or --no-deslop specified)
+- [ ] Post-deslop regression tests pass
+- [ ] `/cancel` run for clean state cleanup
+</Final_Checklist>
+
+<Advanced>
+## PRD Mode (Optional)
+
+When the user provides the `--prd` flag, initialize a Product Requirements Document before starting the ralph loop.
+
+### Detecting PRD Mode
+Check if `{{PROMPT}}` contains `--prd` or `--PRD`.
+
+Prompt-side `$ralph` workflow activation is lighter-weight than `rcs ralph --prd ...`.
+It seeds Ralph workflow state and guidance, but it does not implicitly launch the
+CLI entrypoint or apply the PRD startup gate. Treat `rcs ralph --prd ...` as the
+explicit PRD-gated path.
+
+### Detecting `--no-deslop`
+Check if `{{PROMPT}}` contains `--no-deslop`.
+If `--no-deslop` is present, skip the deslop pass entirely after Step 7 and continue using the latest successful pre-deslop verification evidence.
+
+### Visual Reference Flags (Optional)
+Ralph execution supports visual reference flags for screenshot tasks:
+- Repeatable image inputs: `-i <image-path>` (can be used multiple times)
+- Image directory input: `--images-dir <directory>`
+
+Example:
+`ralph -i refs/hn.png -i refs/hn-item.png --images-dir ./screenshots "match HackerNews layout"`
+
+### PRD Workflow
+1. Run deep-interview in quick mode before creating PRD artifacts:
+   - Execute: `$deep-interview --quick <task>`
+   - Complete a compact requirements pass (context, goals, scope, constraints, validation)
+   - Persist interview output to `.rcs/interviews/{slug}-{timestamp}.md`
+2. Create canonical PRD/progress artifacts:
+   - PRD: `.rcs/plans/prd-{slug}.md`
+   - Progress ledger: `.rcs/state/{scope}/ralph-progress.json` (session scope when available, else root scope)
+3. Parse the task (everything after `--prd` flag)
+4. Break down into user stories:
+
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralph/[feature-name]",
+  "description": "[Feature description]",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Short title]",
+      "description": "As a [user], I want to [action] so that [benefit].",
+      "acceptanceCriteria": ["Criterion 1", "Typecheck passes"],
+      "priority": 1,
+      "passes": false
+    }
+  ]
+}
+```
+
+5. Initialize canonical progress ledger at `.rcs/state/{scope}/ralph-progress.json`
+6. Guidelines: right-sized stories (one session each), verifiable criteria, independent stories, priority order (foundational work first)
+7. Proceed to normal ralph loop using user stories as the task list
+
+### Example
+User input: `--prd build a todo app with React and TypeScript`
+Workflow: Detect flag, extract task, create `.rcs/plans/prd-{slug}.md`, create `.rcs/state/{scope}/ralph-progress.json`, begin ralph loop.
+
+### Legacy compatibility
+- During the compatibility window, Ralph `--prd` startup still validates machine-readable story state from `.rcs/prd.json`.
+- `.rcs/plans/prd-{slug}.md` remains the canonical storage/documentation artifact, but it is not yet the startup validation source.
+- If `.rcs/prd.json` exists and canonical PRD is absent, migrate one-way into `.rcs/plans/prd-{slug}.md`.
+- If `.rcs/progress.txt` exists and canonical progress ledger is absent, import one-way into `.rcs/state/{scope}/ralph-progress.json`.
+- Keep legacy files unchanged for one release cycle.
+
+## Background Execution Rules
+
+**Run in background** (`run_in_background: true`):
+- Package installation (npm install, pip install, cargo build)
+- Build processes (make, project build commands)
+- Test suites
+- Docker operations (docker build, docker pull)
+
+**Run blocking** (foreground):
+- Quick status checks (git status, ls, pwd)
+- File reads and edits
+- Simple commands
+</Advanced>
+
+Original task:
+{{PROMPT}}