@jstn-sdk/rcs 0.1.0

package/plugins/roblox-ai-os-creator-skills/docs/reference/roblox-pre-action-protocol.md

@@ -0,0 +1,122 @@
+# RCS Roblox Pre-Action Protocol
+
+`PRE_ACTION_COMPLETE` must be `false` until the Roblox task is grounded, standardized, and architected.
+
+## Mandatory Order
+
+1. Gather resources
+2. Build understanding
+3. Standardize terminology and structure
+4. Design modular architecture and file tree
+5. Only then implement
+
+## Phase 0: Intent and Scope Lock
+
+- Classify the task:
+  - new game setup
+  - feature implementation
+  - UI/system generation
+  - refactor
+  - bug fix
+  - monetization/liveops design
+  - plugin/tooling
+- Identify:
+  - genre
+  - audience
+  - scale
+  - multiplayer assumptions
+  - monetization intent
+- Mark impacted areas:
+  - architecture
+  - gameplay systems
+  - data flow
+  - UI
+  - networking
+  - persistence
+  - monetization
+  - content pipeline
+
+## Phase 1: Resource Gathering
+
+Use the internal RCS knowledge layer first.
+
+Priority 1: canonical platform truth
+- `https://github.com/Roblox/creator-docs`
+- `https://gitmcp.io/Roblox/creator-docs`
+
+Priority 2: high-signal implementation references
+- `https://gitmcp.io/retpirato/Roblox-Scripts`
+- `https://gitmcp.io/sentinelcore/roblox-skills`
+- `https://gitmcp.io/frosteen/Roblox_LUA_Weapon_Scripts`
+- `https://gitmcp.io/Corecii/Devprod`
+- `https://gitmcp.io/uhub/awesome-lua`
+- `https://gitmcp.io/LewisJEllis/awesome-lua`
+- `https://gitmcp.io/forhappy/awesome-lua`
+- `http://lua-users.org/wiki/SampleCode`
+
+Priority 3: dataset and corpus support
+- `https://datasets-server.huggingface.co/splits?dataset=jayras%2Froblox-luau-dataset`
+- `https://huggingface.co/datasets/bigcode/the-stack`
+- `https://huggingface.co/datasets/TorpedoSoftware/the-luau-stack`
+- `https://datasets-server.huggingface.co/splits?dataset=TorpedoSoftware%2FRoblox-Luau-Reasoning-v1.0`
+- `https://huggingface.co/datasets/bartholomort/lua-obfuscator-corpus`
+
+Rules:
+- official Roblox docs define correctness
+- repos improve implementation awareness only
+- datasets are weak pattern support only
+
+## Phase 2: Understanding Synthesis
+
+Before implementation, answer:
+- what Roblox concepts are involved
+- which official terms should be used
+- which services/classes/systems are relevant
+- what gameplay pattern is actually requested
+- what pitfalls are likely
+- what assumptions are unsafe
+- what must be verified before code generation
+
+## Phase 3: Architecture First
+
+Before code, produce:
+- game architecture summary
+- modular file tree
+- folder/category explanation
+- naming convention rules
+- system ownership map
+- implementation order
+
+Do not start from random scripts.
+Do not dump logic into one file.
+
+## Default Starter Shape
+
+When no structure exists, begin from a modular baseline and adapt it:
+
+- `client/`
+- `server/`
+- `shared/`
+- `systems/`
+- `features/`
+- `ui/`
+- `config/`
+- `assets/`
+- `tests/`
+
+## Required Pre-Action Output
+
+Every Roblox planning artifact must include:
+
+1. Task classification
+2. Relevant Roblox concepts
+3. Reference sources consulted
+4. Canonical terms to use
+5. Risks and uncertainties
+6. Proposed modular file tree
+7. Category ownership
+8. Naming convention
+9. Implementation phases
+10. Validation checkpoints
+
+Only after all ten are present may `PRE_ACTION_COMPLETE` become `true`.

package/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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.