@jstn-sdk/rcs 0.1.0

package/skills/ai-slop-cleaner/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: ai-slop-cleaner
+description: Run an anti-slop cleanup/refactor/deslop workflow
+---
+
+# AI Slop Cleaner Skill
+
+Reduce AI-generated slop with a regression-tests-first, smell-by-smell cleanup workflow that preserves behavior and raises signal quality.
+
+## When to Use
+
+Use this skill when:
+- A code path works but feels bloated, noisy, repetitive, or over-abstracted
+- A user asks to “cleanup”, “refactor”, or “deslop” AI-generated output
+- Follow-up implementation left duplicate code, dead code, weak boundaries, missing tests, fallback-like code, or unnecessary wrapper layers
+- You need a disciplined cleanup workflow without broad rewrites
+
+## GPT-5.5 Guidance Alignment
+
+- Keep outputs concise and evidence-dense unless risk or the user requests more detail.
+- Treat newer user instructions as local workflow updates without discarding earlier non-conflicting constraints.
+- Keep using inspection, tests, diagnostics, and verification until the cleanup is grounded.
+- Proceed automatically through clear, reversible cleanup steps; ask only when a choice materially changes scope or behavior.
+
+## Scoped File Lists and Ralph Workflow
+
+- This skill can accept a **file list scope** instead of a whole feature area.
+- When the caller provides a changed-files list (for example, Ralph session-owned edits), keep the cleanup strictly bounded to those files.
+- In the **Ralph workflow**, the mandatory deslop pass should run this skill on Ralph's changed files only, in standard mode unless the caller explicitly requests otherwise.
+
+## Procedure
+
+1. **Lock behavior with regression tests first**
+   - Identify the behavior that must not change
+   - Add or run targeted regression tests before editing cleanup candidates
+   - If behavior is currently untested, create the narrowest test coverage needed first
+   - For fallback-like code, cover the primary path and any preserved compatibility/fail-safe fallback before cleanup
+
+2. **Create a cleanup plan before code**
+   - List the specific smells to remove
+   - Bound the pass to the requested files/scope
+   - If a file list scope is provided, keep the pass restricted to that changed-files list
+   - Include fallback findings, classifications, and escalation status in the plan
+   - Order fixes from safest/highest-signal to riskiest
+   - Do not start coding until the cleanup plan is explicit
+
+3. **Inventory fallback-like code before editing**
+   - Search the requested scope for fallback-like detection signals: quick hacks, temporary workaround, temporary fallback, just bypass, just skip, fallback if it fails, swallowed errors, silent defaults, broad compatibility shims, and duplicate alternate execution paths
+   - Classify each finding before changing it:
+     - **Masking fallback slop** — hides errors or evidence, bypasses the primary contract, suppresses tests or validation, swallows failures, silently defaults, or adds untested alternate paths
+     - **Grounded compatibility/fail-safe fallback** — is scoped to an external/version/fail-safe boundary, documents the rationale, preserves failure evidence, and has regression tests for both the primary and fallback behavior
+   - Prefer root-cause repair, deletion, boundary repair, or explicit failure behavior before preserving fallback paths
+   - For broad, ambiguous, cross-layer, or architectural fallback-like code, invoke `$ralplan` for consensus resolution before edits
+   - Recursion guard: when already inside ralplan, ralph, team, or another RCS workflow, do not spawn a nested `$ralplan`; record the finding and attach it to the active ralplan, leader, or plan handoff instead
+
+4. **Categorize issues before editing**
+   - **Fallback-like code** — masking fallbacks, workaround branches, bypasses, swallowed errors, silent defaults, broad shims, alternate execution paths
+   - **Duplication** — repeated logic, copy-paste branches, redundant helpers
+   - **Dead code** — unused code, unreachable branches, stale flags, debug leftovers
+   - **Needless abstraction** — pass-through wrappers, speculative indirection, single-use helper layers
+   - **Boundary violations** — hidden coupling, leaky responsibilities, wrong-layer imports or side effects
+   - **Missing tests** — behavior not locked, weak regression coverage, gaps around edge cases
+
+5. **Execute passes one smell at a time**
+   - **Fallback-like code resolution gate** — remove masking fallback slop, repair root causes, or escalate ambiguous cases before continuing
+   - **Pass 1: Dead code deletion**
+   - **Pass 2: Duplicate removal**
+   - **Pass 3: Naming/error handling cleanup**
+   - **Pass 4: Test reinforcement**
+   - Re-run targeted verification after each pass
+   - Avoid bundling unrelated refactors into the same edit set
+
+6. **Run quality gates**
+   - Regression tests stay green
+   - Lint passes
+   - Typecheck passes
+   - Relevant unit/integration tests pass
+   - Static/security scan passes when available
+   - Diff stays minimal and scoped
+   - No new abstractions or dependencies unless explicitly required
+
+7. **Finish with an evidence-dense report**
+   - Changed files
+   - Simplifications made
+   - Fallback findings, classifications, and escalation status
+   - Tests/diagnostics/build checks run
+   - Remaining risks
+   - Residual follow-ups or consciously deferred cleanup
+
+## Output Format
+
+```text
+AI SLOP CLEANUP REPORT
+======================
+
+Scope: [files or feature area]
+Behavior Lock: [targeted regression tests added/run]
+Cleanup Plan: [bounded smells and order]
+Fallback Findings: [none, or finding -> masking fallback slop / grounded compatibility/fail-safe fallback -> escalation status]
+
+Passes Completed:
+- Fallback-like code resolution gate - [root-cause repair, explicit failure behavior, preserved grounded fallback, or ralplan handoff]
+1. Pass 1: Dead code deletion - [concise fix]
+2. Pass 2: Duplicate removal - [concise fix]
+3. Pass 3: Naming/error handling cleanup - [concise fix]
+4. Pass 4: Test reinforcement - [concise fix]
+
+Quality Gates:
+- Regression tests: PASS/FAIL
+- Lint: PASS/FAIL
+- Typecheck: PASS/FAIL
+- Tests: PASS/FAIL
+- Static/security scan: PASS/FAIL or N/A
+
+Changed Files:
+- [path] - [simplification]
+
+Fallback Review:
+- Findings: [fallback-like findings detected]
+- Classification: [masking fallback slop | grounded fallback]
+- Escalation Status: [none | raised to leader/ralplan | no escalation]
+
+Remaining Risks:
+- [none or short deferred item]
+```
+
+## Scenario Examples
+
+**Good:** The user says `continue` after tests already lock behavior and the next smell pass is clear. Continue with the next bounded cleanup pass.
+
+**Good:** The user narrows the scope to a specific file after planning. Keep the regression-tests-first workflow, but apply the new scope locally.
+
+**Bad:** Start rewriting architecture before protecting behavior with tests.
+
+**Bad:** Collapse multiple smell categories into one large refactor with no intermediate verification.
+
+**Bad:** Keep a `fallback if it fails` branch that silently defaults after a swallowed error instead of fixing the root cause or making failure explicit.
+
+**Good:** A version-specific compatibility shim is narrow, documented, preserves error evidence, has primary and fallback regression tests, and is reported as a grounded compatibility/fail-safe fallback.

package/skills/analyze/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: analyze
+description: "Run read-only deep repository analysis and return a ranked synthesis with explicit confidence, concrete file references, and clear evidence-vs-inference boundaries. Use when a user says 'analyze', 'investigate', 'why does', 'what's causing', or needs grounded cross-file explanation before any changes are proposed."
+---
+
+# Analyze — Read-Only Deep Analysis
+
+Use this skill to answer the user’s question through **read-only repository analysis**. The goal is to explain what the codebase most likely says about the question, not to drift into implementation, debugging theater, or generic fix planning.
+
+## Use `$analyze` when
+
+- the user wants a grounded explanation, not code changes
+- the answer requires reading multiple files or tracing behavior across boundaries
+- there are several plausible explanations and they need to be ranked
+- confidence should reflect the strength of the available evidence
+- the user wants to understand architecture, behavior, causality, impact, or tradeoffs before changing anything
+
+Examples:
+- why a workflow behaves a certain way
+- how a feature is wired across modules
+- what likely explains a failure, regression, or mismatch
+- what would be impacted by changing a dependency or contract
+- which interpretation of the current codebase is best supported
+
+## Do not use `$analyze` when
+
+- the user explicitly wants code edits, a fix, or execution — use the appropriate implementation lane instead
+- the user wants a new product plan or acceptance criteria — use `$plan` / `$ralplan`
+- the request is a simple one-file fact lookup — read the file and answer directly
+- the request is purely about running the RCS tmux team runtime — use `$team` only when RCS runtime is active
+
+## Non-negotiable contract
+
+Analyze is **read-only by contract**.
+
+- Do not edit files.
+- Do not turn the answer into an implementation plan.
+- Do not recommend fixes as the primary output.
+- Do not silently switch into execution work.
+- Do not overclaim certainty.
+- Do not invent facts that are not supported by repository evidence.
+- Do not use judgmental, normative, or speculative language that outruns the evidence.
+
+If a next step is helpful, keep it to a **discriminating read-only probe** that would reduce uncertainty.
+
+## Question-aligned synthesis
+
+Answer the user’s actual question first.
+
+- Start from the asked question, not a generic debugger template.
+- Keep the synthesis scoped to what the user needs to know.
+- Scale the depth to the request: for simple or obvious questions, reduce swarm intensity and answer directly after enough reading.
+- For broader questions, expand the search surface but keep the final answer tightly synthesized.
+
+## Evidence rules
+
+Maintain an explicit **evidence-vs-inference distinction**. Every material claim must be labeled as one of:
+
+1. **Evidence** — directly supported by concrete repository artifacts
+2. **Inference** — a reasoned conclusion drawn from evidence
+3. **Unknown** — a question the current repository evidence does not resolve
+
+Never present an inference as if it were direct evidence.
+Never present a guess as if it were an inference.
+Call out uncertainty explicitly when the codebase does not settle the question.
+
+### Acceptable evidence
+
+Prefer stronger evidence over weaker evidence:
+
+1. direct code paths, contracts, tests, generated artifacts, configs, or docs with concrete file references
+2. multiple independent files pointing to the same conclusion
+3. localized behavioral inference from well-supported code structure
+4. weaker contextual clues that remain explicitly marked as tentative
+
+Unsupported speculation is not evidence.
+
+## Parallel exploration policy
+
+Parallel exploration is allowed when it improves quality, but it must stay runtime-safe.
+
+- Default to direct read-only analysis when the answer is simple.
+- When parallelism helps, prefer **native subagents by default** or equivalent in-session parallel exploration when available.
+- Keep parallel lanes bounded: each lane should answer a concrete sub-question or inspect a specific subsystem.
+- Use **`$team` only when RCS runtime is active** and durable tmux-based coordination is actually needed.
+- Do not imply that `$team` is available in plain Codex/App sessions.
+
+A good default split for complex analysis is:
+- one lane for primary code path / contracts
+- one lane for config / orchestration / generated surfaces
+- one lane for tests / docs / secondary corroboration
+
+## Execution policy
+
+- Default to outcome-first progress and completion reporting: state the question, evidence, inference boundaries, and stop condition before adding process detail.
+- Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.
+- If the user says `continue`, keep working from the current analysis state instead of restarting discovery.
+
+## Working method
+
+1. Restate the question in one sentence.
+2. Identify the smallest set of files most likely to answer it.
+3. Read for direct evidence first.
+4. If needed, open bounded parallel exploration lanes.
+5. Compare competing explanations.
+6. Rank the explanations by support.
+7. Return a synthesis that clearly separates evidence from inference.
+
+## Output contract
+
+Structure the answer so the user can see what is known, what is inferred, and how confident the synthesis is.
+
+### Question
+[Restate the user’s question briefly]
+
+### Ranked synthesis
+| Rank | Explanation | Confidence | Basis |
+|------|-------------|------------|-------|
+| 1 | ... | High / Medium / Low | strongest supporting evidence |
+| 2 | ... | High / Medium / Low | why it trails |
+| 3 | ... | High / Medium / Low | why it remains possible |
+
+### Evidence
+- `path/to/file:line-line` — what this artifact directly shows
+- `path/to/file:line-line` — corroborating evidence
+
+### Inference
+- What the evidence most strongly implies
+- Why weaker alternatives were down-ranked
+
+### Unknowns / limits
+- What the repository evidence does not establish
+- What would need to be checked next to reduce uncertainty
+
+## Quality bar
+
+A good analyze response is:
+- read-only and question-aligned
+- ranked rather than flat
+- explicit about confidence
+- concrete about file references
+- careful about evidence vs inference
+- free of unsupported speculation
+- free of normative drift or judgmental filler
+- explicit about the evidence-vs-inference distinction
+- concise for simple cases, broader only when the question truly needs it
+
+Task: {{ARGUMENTS}}

package/skills/ask-claude/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ask-claude
+description: Ask Claude via local CLI and capture a reusable artifact
+---
+
+# Ask Claude (Local CLI)
+
+Use the locally installed Claude CLI as a direct external advisor for focused questions, reviews, or second opinions.
+
+## Usage
+
+```bash
+/ask-claude <question or task>
+```
+
+## Routing
+
+### Preferred: Local CLI execution
+Run Claude through the canonical RCS CLI command path (no MCP routing):
+
+```bash
+rcs ask claude "{{ARGUMENTS}}"
+```
+
+Exact non-interactive Claude CLI command from `claude --help`:
+
+```bash
+claude -p "{{ARGUMENTS}}"
+# equivalent: claude --print "{{ARGUMENTS}}"
+```
+
+If needed, adapt to the user's installed Claude CLI variant while keeping local execution as the default path.
+
+Legacy compatibility entrypoints (`./scripts/ask-claude.sh`, `npm run ask:claude -- ...`) are transitional wrappers.
+
+### Missing binary behavior
+If `claude` is not found, do **not** switch to MCP.
+Instead:
+1. Explain that local Claude CLI is required for this skill.
+2. Ask the user to install/configure Claude CLI.
+3. Provide a quick verification command:
+
+```bash
+claude --version
+```
+
+## Artifact requirement
+After local execution, save a markdown artifact to:
+
+```text
+.rcs/artifacts/claude-<slug>-<timestamp>.md
+```
+
+Minimum artifact sections:
+1. Original user task
+2. Final prompt sent to Claude CLI
+3. Claude output (raw)
+4. Concise summary
+5. Action items / next steps
+
+Task: {{ARGUMENTS}}

package/skills/ask-gemini/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ask-gemini
+description: Ask Gemini via local CLI and capture a reusable artifact
+---
+
+# Ask Gemini (Local CLI)
+
+Use the locally installed Gemini CLI as a direct external advisor for brainstorming, design feedback, and second opinions.
+
+## Usage
+
+```bash
+/ask-gemini <question or task>
+```
+
+## Routing
+
+### Preferred: Local CLI execution
+Run Gemini through the canonical RCS CLI command path (no MCP routing):
+
+```bash
+rcs ask gemini "{{ARGUMENTS}}"
+```
+
+Exact non-interactive Gemini CLI command from `gemini --help`:
+
+```bash
+gemini -p "{{ARGUMENTS}}"
+# equivalent: gemini --prompt "{{ARGUMENTS}}"
+```
+
+If needed, adapt to the user's installed Gemini CLI variant while keeping local execution as the default path.
+
+Legacy compatibility entrypoints (`./scripts/ask-gemini.sh`, `npm run ask:gemini -- ...`) are transitional wrappers.
+
+### Missing binary behavior
+If `gemini` is not found, do **not** switch to MCP.
+Instead:
+1. Explain that local Gemini CLI is required for this skill.
+2. Ask the user to install/configure Gemini CLI.
+3. Provide a quick verification command:
+
+```bash
+gemini --version
+```
+
+## Artifact requirement
+After local execution, save a markdown artifact to:
+
+```text
+.rcs/artifacts/gemini-<slug>-<timestamp>.md
+```
+
+Minimum artifact sections:
+1. Original user task
+2. Final prompt sent to Gemini CLI
+3. Gemini output (raw)
+4. Concise summary
+5. Action items / next steps
+
+Task: {{ARGUMENTS}}

package/skills/autoforge/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: autoforge
+description: Canonical end-to-end creator workflow surface for Roblox Creator Skills
+---
+
+# Autoforge
+
+Use `$autoforge` to run the creator workflow from brief to blueprint to forge with minimal supervision, while still grounding outputs in Roblox fit, fairness, and creator-usable artifacts.
+
+For Roblox implementation tasks, `$autoforge` must still obey the mandatory gate:
+
+1. classify the task
+2. gather Roblox references through the internal RCS knowledge layer
+3. standardize official terminology
+4. design the modular architecture and file tree
+5. only then begin execution
+
+`PRE_ACTION_COMPLETE` must become `true` before any Roblox code generation.

package/skills/autopilot/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: autopilot
+description: "[RCS] Strict autonomous loop: $ralplan -> $ralph -> $code-review"
+---
+
+<Purpose>
+Autopilot is the strict autonomous delivery loop for non-trivial work. Its primary contract is exactly:
+
+```text
+$ralplan -> $ralph -> $code-review
+```
+
+If `$code-review` is not clean, Autopilot returns to `$ralplan` with the review findings as the next planning input, then continues again through `$ralph` and `$code-review` until the review is clean or a hard blocker is reported.
+</Purpose>
+
+<Use_When>
+- User wants hands-off execution from a concrete idea, issue, PRD, or requirements artifact to reviewed code
+- User says `$autopilot`, "autopilot", "auto pilot", "autonomous", "build me", "create me", "make me", "full auto", "handle it all", or "I want a/an..."
+- Task needs planning, implementation, verification, and code review with automatic follow-up when review is not clean
+</Use_When>
+
+<Do_Not_Use_When>
+- User wants to explore options or brainstorm -- use `$plan` / `$ralplan`
+- User says "just explain", "draft only", or "what would you suggest" -- respond conversationally
+- User wants a single focused code change -- use `$ralph` or direct executor work
+- User wants only review/critique of existing code -- use `$code-review`
+</Do_Not_Use_When>
+
+<Strict_Loop_Contract>
+Autopilot must not run a separate broad expansion/planning/execution/QA/validation lifecycle as its primary behavior. It delegates those concerns to the three canonical workflow phases below:
+
+1. **Phase `ralplan`** — consensus planning gate
+   - Ground the task with pre-context intake.
+   - Run or resume `$ralplan` to produce/update PRD and test-spec artifacts.
+   - When returning from a non-clean review, include `return_to_ralplan_reason` and the review findings as first-class planning input.
+   - Required handoff artifact: an approved plan/test spec suitable for `$ralph`.
+
+2. **Phase `ralph`** — implementation + verification loop
+   - Run `$ralph` from the approved ralplan artifacts.
+   - Ralph owns implementation, tests, build/lint/typecheck evidence, deslop where applicable, and architect verification.
+   - Required handoff artifact: implementation evidence and changed-file summary suitable for `$code-review`.
+
+3. **Phase `code-review`** — merge-readiness gate
+   - Run `$code-review` on the diff/artifacts produced by `$ralph`.
+   - A clean review means final recommendation `APPROVE` with architectural status `CLEAR`.
+   - `COMMENT`, `REQUEST CHANGES`, any architectural `WATCH`/`BLOCK`, or any unresolved finding is not clean.
+   - If not clean, increment the review cycle, persist `review_verdict`, set `return_to_ralplan_reason`, and transition back to Phase `ralplan`.
+
+The only normal terminal state is `complete` after a clean code review. Cancellation, blocked credentials, unrecoverable repeated failures, or explicit user stop may terminate earlier with preserved state.
+</Strict_Loop_Contract>
+
+<Pre-context Intake>
+Before Phase `ralplan` starts or resumes:
+1. Derive a task slug from the request.
+2. Reuse the latest relevant `.rcs/context/{slug}-*.md` snapshot 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, run `explore` first for brownfield facts, then run the Socratic `$deep-interview --quick <task>` before `$ralplan`.
+5. Carry the snapshot path in Autopilot state and all handoff artifacts.
+</Pre-context Intake>
+
+<Execution_Policy>
+- Always execute phases in order: `ralplan`, then `ralph`, then `code-review`.
+- Never skip directly from vague/freeform expansion to implementation; unclear input must be clarified or planned through `$ralplan`.
+- A non-clean `$code-review` always returns to `$ralplan`; do not patch findings ad hoc outside the loop.
+- Each phase must write/update Autopilot state before handing off.
+- Use existing hooks, `.rcs/state`, `$ralplan`, `$ralph`, `$code-review`, and pipeline primitives; do not invent a separate execution framework.
+- Continue automatically through safe reversible phase transitions. Ask only for destructive, credential-gated, or materially preference-dependent branches.
+- 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>
+
+<State_Management>
+Use `rcs_state` MCP tools (or `rcs state ... --json` fallback if MCP transport is unavailable) for Autopilot lifecycle state. State must be session-aware when a session id exists.
+
+Required fields:
+
+```json
+{
+  "mode": "autopilot",
+  "active": true,
+  "current_phase": "ralplan",
+  "iteration": 1,
+  "review_cycle": 0,
+  "max_iterations": 10,
+  "phase_cycle": ["ralplan", "ralph", "code-review"],
+  "handoff_artifacts": {
+    "context_snapshot_path": ".rcs/context/<slug>-<timestamp>.md",
+    "ralplan": null,
+    "ralph": null,
+    "code_review": null
+  },
+  "review_verdict": null,
+  "return_to_ralplan_reason": null
+}
+```
+
+- **On start**: `state_write({mode:"autopilot", active:true, current_phase:"ralplan", iteration:1, review_cycle:0, state:{phase_cycle:["ralplan","ralph","code-review"], handoff_artifacts:{context_snapshot_path, ralplan:null, ralph:null, code_review:null}, review_verdict:null, return_to_ralplan_reason:null}})`
+- **On ralplan -> ralph**: set `current_phase:"ralph"`, persist the plan/test-spec paths under `handoff_artifacts.ralplan`.
+- **On ralph -> code-review**: set `current_phase:"code-review"`, persist implementation/test evidence under `handoff_artifacts.ralph`.
+- **On clean review**: set `active:false`, `current_phase:"complete"`, persist `review_verdict:{recommendation:"APPROVE", architectural_status:"CLEAR", clean:true}` and `completed_at`.
+- **On non-clean review**: increment `iteration` and `review_cycle`, set `current_phase:"ralplan"`, persist `review_verdict:{..., clean:false}`, persist `handoff_artifacts.code_review`, and set `return_to_ralplan_reason` to a concise review-driven reason.
+- **On cancellation**: run `$cancel`; preserve progress for resume rather than deleting handoff artifacts.
+</State_Management>
+
+<Continuation_And_Resume>
+When the user says `continue`, `resume`, or `keep going` while Autopilot is active, read `autopilot-state.json` and continue from `current_phase`:
+- `ralplan`: run/update consensus planning from current handoffs and any `return_to_ralplan_reason`.
+- `ralph`: execute the approved plan and record verification evidence.
+- `code-review`: review the current diff and decide clean vs return-to-ralplan.
+- `complete`: report completion evidence; do not restart.
+
+Do not restart discovery or discard handoff artifacts on continuation.
+</Continuation_And_Resume>
+
+<Pipeline_Orchestrator>
+Autopilot may be represented by the configurable pipeline orchestrator (`src/pipeline/`) when useful. The Autopilot pipeline contract is:
+
+```text
+ralplan -> ralph -> code-review
+```
+
+Pipeline state should use `current_phase` values that match the same phase names (`ralplan`, `ralph`, `code-review`, `complete`, `failed`) and should carry `iteration`, `review_cycle`, `handoff_artifacts`, `review_verdict`, and `return_to_ralplan_reason` alongside stage results.
+</Pipeline_Orchestrator>
+
+<Escalation_And_Stop_Conditions>
+- Stop and report a blocker when required credentials/authority are missing.
+- Stop and report when the same review or verification failure recurs across 3 review cycles with no meaningful new plan.
+- Stop when the user says "stop", "cancel", or "abort" and run `$cancel`.
+- Otherwise, continue the loop until `$code-review` is clean.
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] Phase `ralplan` produced/updated approved planning artifacts
+- [ ] Phase `ralph` implemented and verified the plan with fresh evidence
+- [ ] Phase `code-review` returned a clean verdict (`APPROVE` + `CLEAR`)
+- [ ] `review_verdict.clean` is true and `return_to_ralplan_reason` is null
+- [ ] Tests/build/lint/typecheck evidence from Ralph is available in handoff artifacts
+- [ ] Autopilot state is marked `complete` or cancellation state is preserved coherently
+- [ ] User receives a concise summary with plan, implementation, verification, and review evidence
+</Final_Checklist>
+
+<Examples>
+<Good>
+User: `$autopilot implement GitHub issue #42`
+Flow: create/load context snapshot -> `$ralplan` issue plan -> `$ralph` implementation + tests -> `$code-review`; if review requests changes, return to `$ralplan` with findings.
+</Good>
+
+<Good>
+User: `continue`
+Context: Autopilot state says `current_phase:"code-review"`.
+Flow: run `$code-review` on current diff, persist verdict, finish if clean or transition to `ralplan` with findings if not clean.
+</Good>
+
+<Bad>
+Autopilot invents independent "Expansion", "QA", and "Validation" phases and treats them as the primary lifecycle.
+Why bad: this bypasses the strict `$ralplan -> $ralph -> $code-review` contract.
+</Bad>
+</Examples>

package/skills/autoresearch/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: autoresearch
+description: Stateful validator-gated research loop with native-hook persistence
+---
+
+# Autoresearch
+
+Autoresearch is the skill-first replacement for the deprecated `rcs autoresearch` command.
+It keeps the useful measured-research loop, but it now runs as a native-hook stateful workflow instead of a direct CLI or tmux launch surface.
+
+## Use when
+- You want a Ralph-ish persistent research loop
+- The task should keep nudging until explicit validation evidence exists
+- You want init-time choice between script validation and prompt+architect validation
+
+## Do not use when
+- You want the old `rcs autoresearch` command surface (hard-deprecated)
+- You want detached tmux or split-pane launch parity
+- You have not decided the validation regime yet
+
+## Core contract
+1. **Init chooses validation mode.** Pick exactly one:
+   - `mission-validator-script`
+   - `prompt-architect-artifact`
+2. **Persist mode state** in `.rcs/state/.../autoresearch-state.json` including:
+   - `validation_mode`
+   - `completion_artifact_path`
+   - `mission_validator_command` **or** `validator_prompt`
+   - optional `output_artifact_path`
+3. **Completion is artifact-gated.** The loop does not stop because the model says “done”, because a stop hook fired once, or because several turns were no-ops.
+4. **Direct CLI launch is gone.** Use `$deep-interview --autoresearch` for intake and `$autoresearch` for execution.
+
+## Completion artifact contract
+
+### `mission-validator-script`
+The completion artifact must exist and record a passing validator result, for example:
+
+```json
+{
+  "status": "passed",
+  "passed": true,
+  "summary": "metric improved beyond baseline"
+}
+```
+
+### `prompt-architect-artifact`
+The completion artifact must include both an architect approval verdict and an output artifact path, for example:
+
+```json
+{
+  "validator_prompt": "Review the research output against the mission.",
+  "architect_review": { "verdict": "approved" },
+  "output_artifact_path": ".rcs/specs/autoresearch-demo/report.md"
+}
+```
+
+## Recommended flow
+1. Run `$deep-interview --autoresearch` to clarify mission + evaluator.
+2. Materialize `.rcs/specs/autoresearch-{slug}/mission.md`, `sandbox.md`, and `result.json`.
+3. Start `$autoresearch` with the chosen validation mode stored in mode state.
+4. Let stop-hook / auto-nudge continue until the completion artifact satisfies the chosen validation mode.
+5. Finish only after the validator artifact is complete.
+
+## Migration note
+- `rcs autoresearch` is hard-deprecated.
+- No direct CLI launch.
+- No tmux split-pane launch.
+- No noop-count completion gate.