@jstn-sdk/rcs 0.1.0

package/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}}

package/skills/ralph-init/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ralph-init
+description: Initialize a PRD (Product Requirements Document) for structured ralph-loop execution
+---
+
+# Ralph Init
+
+Initialize a PRD (Product Requirements Document) for structured ralph-loop execution. Creates a structured requirements document that Ralph can use for goal-driven iteration.
+
+## Usage
+
+```
+/ralph-init "project or feature description"
+```
+
+## Behavior
+
+1. **Gather requirements** via interactive interview or from the provided description
+2. **Create PRD** at `.rcs/plans/prd-{slug}.md` with:
+   - Problem statement
+   - Goals and non-goals
+   - Acceptance criteria (testable)
+   - Technical constraints
+   - Implementation phases
+3. **Link to Ralph** so that `/ralph` can use the PRD as its completion criteria
+4. **Initialize/ensure canonical progress ledger** at `.rcs/state/{scope}/ralph-progress.json` (session scope if active session exists)
+
+### Canonical source contract
+
+- Canonical PRD source of truth is `.rcs/plans/prd-{slug}.md`.
+- Ralph progress source of truth is `.rcs/state/{scope}/ralph-progress.json` (session scope when available).
+- During the current compatibility window, Ralph `--prd` startup still validates machine-readable story state from `.rcs/prd.json`.
+- Legacy `.rcs/prd.json` / `.rcs/progress.txt` inputs migrate one-way into canonical artifacts, but canonical PRD markdown is not yet the startup validation source for `rcs ralph --prd ...`.
+
+## Output
+
+A structured PRD file saved to `.rcs/plans/` that serves as the definition of done for Ralph execution.
+
+## Next Steps
+
+After creating the PRD, start execution with:
+```
+/ralph "implement the PRD"
+```
+
+Ralph will iterate until all acceptance criteria in the PRD are met and architect-verified.

package/skills/ralplan/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: ralplan
+description: Alias for $plan --consensus
+---
+
+# Ralplan (Consensus Planning Alias)
+
+Ralplan is a shorthand alias for `$plan --consensus`. It triggers iterative planning with Planner, Architect, and Critic agents until consensus is reached, with **RALPLAN-DR structured deliberation** (short mode by default, deliberate mode for high-risk work).
+
+## Usage
+
+```
+$ralplan "task description"
+```
+
+## Flags
+
+- `--interactive`: Enables user prompts at key decision points (draft review in step 2 and final approval in step 6). Without this flag the workflow runs fully automated — Planner → Architect → Critic loop — and outputs the final plan without asking for confirmation.
+- `--deliberate`: Forces deliberate mode for high-risk work. Adds pre-mortem (3 scenarios) and expanded test planning (unit/integration/e2e/observability). Without this flag, deliberate mode can still auto-enable when the request explicitly signals high risk (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage).
+
+## Usage with interactive mode
+
+```
+$ralplan --interactive "task description"
+```
+
+## Behavior
+
+## GPT-5.5 Guidance Alignment
+
+Use 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, right-sized implementation/PRD shape, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches.
+
+This skill invokes the Plan skill in consensus mode:
+
+```
+$plan --consensus <arguments>
+$plan --consensus --interactive <arguments>
+```
+
+The consensus workflow:
+1. **Planner** creates an adaptive plan (right-sized to task scope; do not default to exactly five steps) and a compact **RALPLAN-DR summary** before review:
+   - Principles (3-5)
+   - Decision Drivers (top 3)
+   - Viable Options (>=2) with bounded pros/cons
+   - If only one viable option remains, explicit invalidation rationale for alternatives
+   - Deliberate mode only: pre-mortem (3 scenarios) + expanded test plan (unit/integration/e2e/observability)
+2. **User feedback** *(--interactive only)*: If `--interactive` is set, use the structured question UI (`rcs question` in attached tmux; native structured input outside tmux when available) to present the draft plan **plus the Principles / Drivers / Options summary** before review (Proceed to review / Request changes / Skip review). Otherwise, automatically proceed to review.
+3. **Architect** reviews for architectural soundness and must provide the strongest steelman antithesis, at least one real tradeoff tension, and (when possible) synthesis — **await completion before step 4**. In deliberate mode, Architect should explicitly flag principle violations.
+4. **Critic** evaluates against quality criteria — run only after step 3 completes. Critic must enforce principle-option consistency, fair alternatives, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. In deliberate mode, Critic must reject missing/weak pre-mortem or expanded test plan.
+5. **Re-review loop** (max 5 iterations): Any non-`APPROVE` Critic verdict (`ITERATE` or `REJECT`) MUST run the same full closed loop:
+   a. Collect Architect + Critic feedback
+   b. Revise the plan with Planner
+   c. Return to Architect review
+   d. Return to Critic evaluation
+   e. Repeat this loop until Critic returns `APPROVE` or 5 iterations are reached
+   f. If 5 iterations are reached without `APPROVE`, present the best version to the user
+6. On Critic approval *(--interactive only)*: If `--interactive` is set, use the structured question UI to present the plan with approval options (Approve and execute via ralph / Approve and implement via team / Request changes / Reject). Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups), an explicit available-agent-types roster, concrete follow-up staffing guidance for both `ralph` and `team`, suggested reasoning levels by lane, explicit `rcs team` / `$team` launch hints, and a concrete **team verification** path. Otherwise, output the final plan and stop.
+7. *(--interactive only)* User chooses: Approve (ralph or team), Request changes, or Reject
+8. *(--interactive only)* On approval: invoke `$ralph` for sequential execution or `$team` for parallel team execution with the explicit available-agent-types roster, reasoning-by-lane guidance, role/staffing allocation guidance, launch hints, and verification-path guidance from the approved plan -- never implement directly
+
+> **Important:** Steps 3 and 4 MUST run sequentially. Do NOT issue both agent calls in the same parallel batch. Always await the Architect result before invoking Critic.
+
+Follow the Plan skill's full documentation for consensus mode details.
+
+## Pre-context Intake
+
+Before consensus planning or execution handoff, ensure a grounded context snapshot exists:
+
+1. Derive a task slug from the request.
+2. Reuse the latest relevant snapshot in `.rcs/context/{slug}-*.md` when available.
+3. If none exists, create `.rcs/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
+   - task statement
+   - desired outcome
+   - known facts/evidence
+   - constraints
+   - unknowns/open questions
+   - likely codebase touchpoints
+4. If ambiguity remains 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>` before continuing.
+5. If the plan depends on official docs, version-aware framework guidance, best practices, or external dependency behavior, auto-delegate `researcher` before finalizing the planning handoff so execution does not start from repo-local recall alone.
+
+Do not hand off to execution modes until this intake is complete; if urgency forces progress, explicitly document the risk tradeoffs.
+
+## Pre-Execution Gate
+
+### Why the Gate Exists
+
+Execution modes (ralph, autopilot, team, ultrawork) spin up heavy multi-agent orchestration. When launched on a vague request like "ralph improve the app", agents have no clear target — they waste cycles on scope discovery that should happen during planning, often delivering partial or misaligned work that requires rework.
+
+The ralplan-first gate intercepts underspecified execution requests and redirects them through the ralplan consensus planning workflow. This ensures:
+- **Explicit scope**: A PRD defines exactly what will be built
+- **Test specification**: Acceptance criteria are testable before code is written
+- **Consensus**: Planner, Architect, and Critic agree on the approach
+- **No wasted execution**: Agents start with a clear, bounded task
+
+### Good vs Bad Prompts
+
+**Passes the gate** (specific enough for direct execution):
+- `ralph fix the null check in src/hooks/bridge.ts:326`
+- `autopilot implement issue #42`
+- `team add validation to function processKeywordDetector`
+- `ralph do:\n1. Add input validation\n2. Write tests\n3. Update README`
+- `ultrawork add the user model in src/models/user.ts`
+
+**Gated — redirected to ralplan** (needs scoping first):
+- `ralph fix this`
+- `autopilot build the app`
+- `team improve performance`
+- `ralph add authentication`
+- `ultrawork make it better`
+
+**Bypass the gate** (when you know what you want):
+- `force: ralph refactor the auth module`
+- `! autopilot optimize everything`
+
+### When the Gate Does NOT Trigger
+
+The gate auto-passes when it detects **any** concrete signal. You do not need all of them — one is enough:
+
+| Signal Type | Example prompt | Why it passes |
+|---|---|---|
+| File path | `ralph fix src/hooks/bridge.ts` | References a specific file |
+| Issue/PR number | `ralph implement #42` | Has a concrete work item |
+| camelCase symbol | `ralph fix processKeywordDetector` | Names a specific function |
+| PascalCase symbol | `ralph update UserModel` | Names a specific class |
+| snake_case symbol | `team fix user_model` | Names a specific identifier |
+| Test runner | `ralph npm test && fix failures` | Has an explicit test target |
+| Numbered steps | `ralph do:\n1. Add X\n2. Test Y` | Structured deliverables |
+| Acceptance criteria | `ralph add login - acceptance criteria: ...` | Explicit success definition |
+| Error reference | `ralph fix TypeError in auth` | Specific error to address |
+| Code block | `ralph add: \`\`\`ts ... \`\`\`` | Concrete code provided |
+| Escape prefix | `force: ralph do it` or `! ralph do it` | Explicit user override |
+
+### End-to-End Flow Example
+
+1. User types: `ralph add user authentication`
+2. Gate detects: execution keyword (`ralph`) + underspecified prompt (no files, functions, or test spec)
+3. Gate redirects to **ralplan** with message explaining the redirect
+4. Ralplan consensus runs:
+   - **Planner** creates initial plan (which files, what auth method, what tests)
+   - **Architect** reviews for soundness
+   - **Critic** validates quality and testability
+5. On consensus approval, user chooses execution path:
+   - **ralph**: sequential execution with verification
+   - **team**: parallel coordinated agents
+6. Execution begins with a clear, bounded plan
+
+### Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Gate fires on a well-specified prompt | Add a file reference, function name, or issue number to anchor the request |
+| Want to bypass the gate | Prefix with `force:` or `!` (e.g., `force: ralph fix it`) |
+| Gate does not fire on a vague prompt | The gate only catches prompts with <=15 effective words and no concrete anchors; add more detail or use `$ralplan` explicitly |
+| Redirected to ralplan but want to skip planning | In the ralplan workflow, say "just do it" or "skip planning" to transition directly to execution |
+
+## 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.

package/skills/rcs-setup/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: rcs-setup
+description: Setup and configure Roblox Creator Skills using current CLI behavior
+---
+
+# RCS Setup
+
+Use this skill when users want to install or refresh Roblox Creator Skills for the **current project plus user-level RCS directories**.
+
+## Command
+
+```bash
+rcs setup [--force] [--merge-agents] [--dry-run] [--verbose] [--scope <user|project>] [--plugin|--legacy|--install-mode <legacy|plugin>]
+```
+
+If you only want lightweight `AGENTS.md` scaffolding for an existing repo or subtree, use `rcs agents-init [path]` instead of full setup.
+
+Supported setup flags (current implementation):
+- `--force`: overwrite/reinstall managed artifacts where applicable
+- `--merge-agents`: when `AGENTS.md` already exists, preserve user-authored content and insert/refresh RCS-managed generated sections between explicit `<!-- RCS:AGENTS:START -->` / `<!-- RCS:AGENTS:END -->` markers
+- `--dry-run`: print actions without mutating files
+- `--verbose`: print per-file/per-step details
+- `--scope`: choose install scope (`user`, `project`)
+- `--plugin`: use Codex plugin delivery for bundled skills while archiving/removing legacy RCS-managed prompts/native agents and keeping setup-owned runtime hooks
+- `--legacy`: use legacy setup delivery, overriding any persisted plugin install mode
+- `--install-mode`: explicitly choose setup delivery mode (`legacy` or `plugin`); canonical form for scripted setup
+
+## What this setup actually does
+
+`rcs setup` performs these steps:
+
+1. Resolve setup scope:
+   - `--scope` explicit value
+   - else persisted `./.rcs/setup-scope.json` (with automatic migration of legacy values)
+   - if a TTY user has persisted setup preferences, `rcs setup` first summarizes the recorded choices and asks whether to **keep**, **review/change**, or **reset** them
+   - else interactive prompt on TTY (default `user`)
+   - else default `user` (safe for CI/tests)
+2. If scope is `user`, resolve user skill delivery mode:
+   - explicit `--plugin`, `--legacy`, or `--install-mode legacy|plugin`, if present
+   - persisted install mode in `./.rcs/setup-scope.json`, if present and the TTY review decision is `keep`
+   - else discovered installed plugin cache under `${CODEX_HOME:-~/.codex}/plugins/cache/**/.codex-plugin/plugin.json` with `name: roblox-ai-os-creator-skills` makes `plugin` the default
+   - else interactive prompt on TTY (`legacy` by default, or `plugin` when a plugin cache is discovered)
+   - else default `legacy` unless a plugin cache is discovered
+3. Create directories and persist effective scope/install mode
+4. In legacy mode, install prompts/native agents/skills and merge full config.toml. In plugin mode, archive/remove legacy RCS-managed prompts/native agents/skills but keep native Codex hooks installed.
+5. Verify Team CLI API interop markers exist in built `dist/cli/team.js`
+6. Generate AGENTS.md defaults only when selected/allowed (or legacy behavior outside plugin mode)
+7. Configure notify hook references outside plugin mode and write `./.rcs/hud-config.json`
+
+## Important behavior notes
+
+- `rcs setup` prompts for scope when no scope is provided and stdin/stdout are TTY. If `./.rcs/setup-scope.json` already exists, setup now summarizes the saved choices first and asks whether to keep them, review/change them, or reset and behave like a fresh setup run.
+- Non-interactive setup never blocks for this review prompt: it keeps deterministic CLI/persisted/default behavior for CI and scripted installs.
+- In `user` scope, `rcs setup` also prompts for skill delivery mode when no prior install mode is kept; installed plugin cache discovery makes plugin mode the default prompt/non-interactive choice.
+- Local project orchestration file is `./AGENTS.md` (project root).
+- If `AGENTS.md` exists and neither `--force` nor `--merge-agents` is used, interactive TTY runs ask whether to overwrite. Non-interactive runs preserve the file.
+- Use `--merge-agents` to keep existing project guidance while allowing setup to refresh RCS-managed AGENTS sections and the generated model capability table idempotently.
+- Scope targets:
+  - `user`: user directories (`~/.codex`, `~/.codex/skills`, `~/.rcs/agents`)
+  - `project`: local directories (`./.codex`, `./.codex/skills`, `./.rcs/agents`)
+- User-scope skill delivery targets:
+  - `legacy`: keep installing/updating RCS skills in the resolved user skill root
+  - `plugin`: rely on Codex plugin discovery for bundled skills and archive/remove legacy RCS-managed prompts/skills/native agents; setup still installs native Codex hooks and `codex_hooks = true` because plugins do not carry hooks.
+- Migration hint: in `user` scope, if historical `~/.agents/skills` still exists alongside `${CODEX_HOME:-~/.codex}/skills`, current setup prints a cleanup hint. **Why the paths differ**: `${CODEX_HOME:-~/.codex}/skills/` is the path current Codex CLI natively loads as its skill root; `~/.agents/skills/` was the skill root in an older Codex CLI release before `~/.codex` became the standard home directory. RCS writes only to the canonical `${CODEX_HOME:-~/.codex}/skills/` path. When both directories exist simultaneously, Codex discovers skills from both trees and may show duplicate entries in Enable/Disable Skills. Archive or remove `~/.agents/skills/` to resolve this.
+- If persisted scope is `project`, `rcs` launch automatically uses `CODEX_HOME=./.codex` unless user explicitly overrides `CODEX_HOME`.
+- Plugin mode prompts separately for optional AGENTS.md defaults and optional `developer_instructions` defaults. If `developer_instructions` already exists, setup asks before overwriting it; non-interactive runs preserve it.
+- With `--force` or `--merge-agents`, AGENTS updates may still be skipped if an active RCS session is detected (safety guard).
+- Legacy persisted scope values (`project-local`) are automatically migrated to `project` with a one-time warning.
+
+## Setup-owned configuration surfaces
+
+Use this map when reconciling setup behavior or debugging a confusing install:
+
+| Surface | Owner | Notes |
+| --- | --- | --- |
+| `./.rcs/setup-scope.json` | `rcs setup` | Persists setup scope and user-scope skill delivery mode. TTY reruns summarize it and offer keep/review/reset. |
+| `~/.codex/config.toml` / `./.codex/config.toml` | `rcs setup` generated blocks + user edits | Setup refreshes RCS-managed blocks while preserving supported manual content. |
+| `~/.codex/hooks.json` / `./.codex/hooks.json` | `rcs setup` shared ownership | Setup owns RCS native hook wrappers and preserves user-owned hooks. |
+| prompts, skills, native agents | `rcs setup` or Codex plugin delivery | Legacy mode installs local files; plugin mode relies on plugin discovery for bundled skills and archives/removes legacy RCS-managed prompt/native-agent copies. |
+| `AGENTS.md` | `rcs setup` with overwrite safety | Generated defaults or managed refreshes are guarded by force/session checks. |
+| `./.rcs/hud-config.json` | `rcs setup` / `$hud` | Setup creates the focused default; `$hud` can adjust it later. |
+| notification hooks | `rcs setup` / `$configure-notifications` | Setup wires defaults outside plugin skill delivery; notification skill owns deeper provider configuration. |
+
+## If `$rcs-setup` is missing or stale
+
+The source repo ships `skills/rcs-setup/SKILL.md` and the catalog marks it active. If Codex does not show `$rcs-setup`, treat it as an installation/discovery issue rather than a missing source skill:
+
+1. Run `rcs setup --verbose` in the intended scope.
+2. Run `rcs doctor` and check the reported setup scope, Codex home, skill root, and hook/config status.
+3. If using project scope, confirm `./.codex/skills/rcs-setup/SKILL.md` exists.
+4. If using user scope, confirm `${CODEX_HOME:-~/.codex}/skills/rcs-setup/SKILL.md` exists in legacy mode, or that the Roblox Creator Skills plugin is installed/discovered in plugin mode.
+5. If duplicate/stale skills appear, check for legacy `~/.agents/skills` overlap and follow the cleanup hint printed by setup/doctor.
+
+## Recommended workflow
+
+1. Run setup:
+
+```bash
+rcs setup --force --verbose
+```
+
+2. Verify installation:
+
+```bash
+rcs doctor
+```
+
+3. Start Codex with RCS in the target project directory.
+
+## Expected verification indicators
+
+From `rcs doctor`, expect:
+- Prompts installed (scope-dependent: user or project)
+- Skills installed (scope-dependent: user or project)
+- AGENTS.md found in project root
+- `.rcs/state` exists
+- RCS MCP servers configured in scope target `config.toml` (`~/.codex/config.toml` or `./.codex/config.toml`)
+
+## Troubleshooting
+
+- If using local source changes, run build first:
+
+```bash
+npm run build
+```
+
+- If your global `rcs` points to another install, run local entrypoint:
+
+```bash
+node bin/rcs.js setup --force --verbose
+node bin/rcs.js doctor
+```
+
+- If AGENTS.md was not overwritten during `--force`, stop active RCS session and rerun setup.
+- If AGENTS.md was not merged during `--merge-agents`, stop active RCS session and rerun setup.

package/skills/review/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: review
+description: Reviewer-only pass for /plan --review and cleanup artifact review
+---
+
+# Review (Reviewer-Only Pass)
+
+Review is a shorthand alias for `/plan --review`. It triggers Critic evaluation of an existing plan and is intended to preserve writer/reviewer separation.
+
+## Usage
+
+```
+/review
+/review "path/to/plan.md"
+```
+
+## Behavior
+
+This skill invokes the Plan skill in review mode:
+
+```
+/plan --review <arguments>
+```
+
+The review workflow:
+1. Treat review as a reviewer-only pass. The authoring context may write the plan or cleanup proposal, but a separate reviewer context must issue the verdict.
+2. Read plan file from `.rcs/plans/` (or specified path)
+3. Evaluate via Critic agent
+4. For cleanup/refactor/anti-slop work, confirm the artifact includes a cleanup plan, regression-test coverage or an explicit test gap, bounded smell-by-smell passes, and quality gates.
+5. Return verdict: APPROVED, REVISE (with specific feedback), or REJECT (replanning required)
+
+## Guardrails
+
+- Never write and approve in the same context.
+- If the current context authored the artifact, hand review to Critic or another reviewer role.
+- Approval must cite concrete evidence, not author claims.
+
+Follow the Plan skill's full documentation for review mode details.