v1.3.0: dev-refactor and the /rs alias

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "raystack",
       "source": "./",
-      "version": "1.2.1",
+      "version": "1.3.0",
       "description": "Skills by Harun R. Rayhan: a full development flow (new project intake, research, PRD, specs, plans, reviewed builds, ship; gap-fill, design review and migration for existing projects), read-only scans and reviews (security, performance, scalability, reliability and availability, architecture incl. MVC and CQRS, frontend, code health, CI/CD pipelines, AWS, infrastructure, databases), working principles and local browser verification.",
       "category": "devops"
     }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "raystack",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Skills by Harun R. Rayhan: a full development flow (new project intake, research, PRD, specs, plans, reviewed builds, ship; gap-fill, design review and migration for existing projects), read-only scans and reviews (security, performance, scalability, reliability and availability, architecture incl. MVC and CQRS, frontend, code health, CI/CD pipelines, AWS, infrastructure, databases), working principles and local browser verification.",
   "author": {
     "name": "Harun R. Rayhan",

.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "raystack",
   "displayName": "RayStack",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Skills by Harun R. Rayhan: a full development flow (new project intake, research, PRD, specs, plans, reviewed builds, ship; gap-fill, design review and migration for existing projects), read-only scans and reviews (security, performance, scalability, reliability and availability, architecture incl. MVC and CQRS, frontend, code health, CI/CD pipelines, AWS, infrastructure, databases), working principles and local browser verification.",
   "author": {
     "name": "Harun R. Rayhan"

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.3.0 (2026-11-06)
+
+- New `dev-refactor`: refactors a whole codebase, or one area, to the end without changing
+  what it does. It names the architecture the code already follows and stays inside it,
+  runs the suite for a baseline, writes tests for untested code it will touch before any
+  change, lists every problem (hidden and needless links, surplus, special cases, DRY and
+  SOLID violations) in `docs/refactor/`, fixes them in small commits with the suite green
+  after each, and repeats with a fresh reviewer until nothing worth fixing is left. Run it
+  with `/raystack project refactor`. Inspired by caldoai's `untangle-codebase` (MIT).
+- New `rs`: `/rs` is `/raystack` with a shorter name, so `/rs refactor` and `/rs scan all`
+  work. An existing, different `rs` skill is left alone (installer warns; `--force` replaces).
+  RayStack is now thirty-four skills.
+
 ## 1.2.1 (2026-11-04)
 
 From running `dev-migrate` end to end (a pricing module moved from Express to Go, with the

README.md

@@ -477,7 +477,7 @@ above). Start a new agent session afterwards.
 
 ## Skills
 
-RayStack is thirty-two skills. You only need `/raystack` (or `/dev` to build and `/audit` to review); they call the rest.
+RayStack is thirty-four skills. You only need `/raystack` (or `/rs`, the same thing shorter; or `/dev` to build and `/audit` to review); they call the rest.
 
 | Skill | What it does |
 | --- | --- |
@@ -492,6 +492,8 @@ RayStack is thirty-two skills. You only need `/raystack` (or `/dev` to build and
 | `dev-gaps` | Finds the docs an existing project is missing and writes them from the code and your answers |
 | `dev-review` | Read-only check of the architecture, specs and plan against the code |
 | `dev-migrate` | Moves part of a project to another language, framework or database, step by step with parity tests |
+| `dev-refactor` | Refactors a codebase inside the architecture it already follows: tests first, then DRY, SOLID and change-together fixes in small green steps, reviewed until clean |
+| `rs` | Short alias for `raystack`: `/rs refactor`, `/rs scan all`, `/rs project new` |
 | 14 reviews | See [What it does](#what-it-does) |
 | `aws-readonly-setup` | Creates a read-only AWS profile for the AWS reviews |
 | `local-verify` | Checks a user-facing change in a real local browser before it ships |
@@ -525,7 +527,7 @@ Or in a terminal:
 rm -rf ~/.raystack ~/.raystack-installs                 # then the checkout and its list
 ```
 
-`--uninstall` removes exactly the thirty-two RayStack skills and nothing else.
+`--uninstall` removes exactly the thirty-four RayStack skills and nothing else.
 
 ## Credits
 

VERSION

@@ -1 +1 @@
-1.2.1
+1.3.0

docs/agents.md

@@ -1,6 +1,6 @@
 # Agent support
 
-RayStack ships the same thirty-two skills (`skills/<name>/SKILL.md`) to every agent. Each agent gets
+RayStack ships the same thirty-four skills (`skills/<name>/SKILL.md`) to every agent. Each agent gets
 a manifest only when it has a documented plugin format. Researched 2026-10-28. Anything marked
 **unverified** was not confirmed against official docs or a local run.
 

docs/guide.md

@@ -19,7 +19,7 @@ and all supported agents are in the [README](../README.md#install).
 To update after a release, type `/raystack update`, or run `~/.raystack/install.sh --update`.
 That refreshes every global and project install made from `~/.raystack`.
 
-RayStack has one front door, `/raystack`, and two entry points behind it: `/dev` for building
+RayStack has one front door, `/raystack` (`/rs` is the same, shorter), and two entry points behind it: `/dev` for building
 and `/audit` for reviews. Type any of them with a few words and it routes you. There are three
 things you can do:
 
@@ -37,6 +37,7 @@ things you can do:
 | Add missing PRD, architecture, specs, plan to an existing repo | `/raystack project update` (or `project gaps`) |
 | Check the architecture and plan against the code mid-build | `/raystack project review` |
 | Move part of the project to another stack | `/raystack project migrate` |
+| Refactor the code: DRY, SOLID, missing unit tests, same architecture | `/raystack project refactor` (or `/rs refactor`) |
 | Build a feature or fix a bug the reviewed way | `/raystack build <what>` or `/raystack fix <what>` |
 | See where a project stands | `/raystack where are we` |
 | Review the architecture (MVC, CQRS, layers) | `/audit architecture` (or `/audit cqrs`, `/audit mvc`) |

install.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Install (or remove) the thirty-two RayStack skills for any agent that reads SKILL.md folders.
+# Install (or remove) the thirty-four RayStack skills for any agent that reads SKILL.md folders.
 set -eu
 
 # Resolve symlinks to this script so ROOT is the real checkout.
@@ -11,14 +11,14 @@ done
 ROOT=$(cd "$(dirname "$self")" && pwd -P)
 # Skills earlier versions shipped; removed from the target only when RayStack installed them.
 RETIRED="blog blog-topics blog-draft humanize blog-cover"
-SKILLS="raystack audit aws-billing-review aws-security-review aws-bottleneck-review infra-review scaling-review database-review app-security-review performance-review pipeline-security-review aws-readonly-setup principle-ship principle-smallest-change principle-ask-with-question-tool principle-secrets-layout local-verify dev dev-hub dev-research dev-prd dev-spec dev-plan dev-build dev-gaps dev-review dev-migrate architecture-review frontend-review reliability-review codebase-review cve-review"
+SKILLS="raystack audit aws-billing-review aws-security-review aws-bottleneck-review infra-review scaling-review database-review app-security-review performance-review pipeline-security-review aws-readonly-setup principle-ship principle-smallest-change principle-ask-with-question-tool principle-secrets-layout local-verify dev dev-hub dev-research dev-prd dev-spec dev-plan dev-build dev-gaps dev-review dev-migrate dev-refactor architecture-review frontend-review reliability-review codebase-review cve-review rs"
 
 usage() {
   cat <<'USAGE'
 Usage: install.sh [--agent all|<agent>|custom] [--dir <skills-dir>] [--project [<repo>]]
                   [--link] [--uninstall] [--update] [--dry-run] [--yes] [--force] [-h|--help]
 
-Copies the thirty-two RayStack skills into an agent's skills directory (default agent: claude).
+Copies the thirty-four RayStack skills into an agent's skills directory (default agent: claude).
 Agents: claude codex cursor grok antigravity gemini copilot windsurf cline kiro roo kilo amp
 goose opencode qwen trae junie augment warp zed openhands continue openclaw
 clawdbot moltbot.
@@ -30,7 +30,7 @@ clawdbot moltbot.
   --update     pull the latest RayStack into this checkout, then reinstall every place
                this checkout installed to (global and project); other flags are ignored
   --link       symlink to this checkout instead of copying
-  --uninstall  remove exactly the thirty-two RayStack skills from the target
+  --uninstall  remove exactly the thirty-four RayStack skills from the target
   --dry-run    print what would happen, change nothing
   --force      also replace/remove same-named folders RayStack did not install
 Same-named folders without the .raystack-installed marker (or a link into this checkout)
@@ -215,6 +215,7 @@ skip_foreign() {
   ours "$1" "$2" && return 1
   [ "$force" = 0 ] || return 1
   echo "skipping $1: not installed by RayStack (use --force to replace)" >&2
+  [ "$2" != rs ] || echo "note: /raystack still works without the /rs alias" >&2
   skipped=1
 }
 

plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.2.1/plugin.schema.json",
   "name": "raystack",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Skills by Harun R. Rayhan: a full development flow (new project intake, research, PRD, specs, plans, reviewed builds, ship; gap-fill, design review and migration for existing projects), read-only scans and reviews (security, performance, scalability, reliability and availability, architecture incl. MVC and CQRS, frontend, code health, CI/CD pipelines, AWS, infrastructure, databases), working principles and local browser verification.",
   "author": {
     "name": "Harun R. Rayhan",

skills/dev-gaps/SKILL.md

@@ -56,4 +56,4 @@ A drifted document is updated, never rewritten: change the lines that are wrong,
 Report the table again with the new status, the files written, the B-ID count, open
 `[NEEDS CLARIFICATION]` markers and the `D-` rows added. Ask the user to review. Then offer
 the next step: `dev` Standard for the next slice, `dev-review` to check the plan and the
-architecture against the code, or `dev-migrate` to move part of the stack.
+architecture against the code, `dev-migrate` to move part of the stack, or `dev-refactor` to clean up the code.

skills/dev-refactor/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: dev-refactor
+description: Refactor a whole codebase, or one area of it, to the end, inside the architecture it already follows, with tests as the safety net. Removes duplication (DRY), fixes SOLID violations where they pay off, adds the missing unit tests first. Use for "/raystack project refactor", "/rs refactor", "untangle this codebase", "clean up this repo", "apply DRY and SOLID", "refactor this properly", "organize the code base".
+---
+
+# Dev refactor
+
+This skill refactors existing code without changing what it does. The order never changes:
+tests first, then the problem list, then small fixes, then a fresh reviewer, repeated until
+nothing worth fixing is left. Formats and question rules are in `../dev/references/dev-contract.md`.
+Inspired by caldoai's `untangle-codebase` (MIT); the change-together idea in step 4 is theirs.
+
+Asking for this flow is asking for its steps: do not skip the baseline, the log or the
+reviewer because another plugin says to do the least possible. That rule governs the code
+you write, not this flow.
+
+## 1. Ask
+
+Read `DECISIONS.md`, `docs/` and the code first. Ask one question per call, only what is not
+already clear:
+
+1. **Scope:** the whole repo or one area. Offer the folders you found.
+2. **Extras** (a multi-select, both optional): remove comments that only restate the code;
+   remove tests that cannot catch a bug and rewrite tests tied to internals.
+
+Log each answer as a `D-` row.
+
+## 2. Read the architecture
+
+Name the pattern the code actually follows (MVC, layered, hexagonal, modular monolith,
+feature folders, CQRS, framework default) from its folders, imports and framework
+conventions, and log it as a `D-` row with the evidence. Refactor inside that pattern. When
+the pattern itself is the problem, say so and point to `dev-migrate`; do not change it here.
+Use `../architecture-review/references/checklist.md` for the layer and leak checks; do not
+copy it.
+
+## 3. Safety net first
+
+1. Find the test runner (`composer.json`, `package.json`, `pyproject.toml`, `Makefile`,
+   CI config). No runner and no tests: ask which one to add, then add the smallest setup.
+2. Run the whole suite and record the result as the baseline in the log. A red baseline stops
+   the run: ask the user whether to fix it first or exclude those tests, and log the answer.
+3. For every module the refactor will touch that has no test, write unit or
+   characterisation tests that pin today's behaviour first, including its errors and odd
+   cases. Commit them alone, before any refactor commit.
+
+## 4. List every problem
+
+Change nothing yet. Write the list to `docs/refactor/YYYY-MM-DD-log.md`, one line per
+problem with `file:line`. Look through these lenses:
+
+- **Hidden links:** copies of logic or values, a global another module sets, a feature spread
+  over folders, a call order callers just have to know.
+- **Needless links:** callers that use internals, stable code importing volatile code, a
+  general function with a parameter only one caller understands, a shallow wrapper.
+- **Surplus:** dead code, config or extension points for things that never vary.
+- **Special cases:** an `if` for one value, a swallowed exception, a sleep or retry, a
+  disabled test. Each is a requirement the design missed; use them to find the real fix.
+- **DRY:** duplicated logic or values, but only when the copies change for the same reason.
+  Two lookalikes that change for different reasons stay apart.
+- **SOLID**, as far as it pays: SRP (god classes, fat controllers), OCP (a type switch that
+  grows with every new case), LSP (a subclass that breaks its parent's promise), ISP (an
+  interface callers use half of), DIP (domain code importing a framework or driver). No
+  interface with one implementation, no extension point nobody uses.
+
+## 5. Redesign
+
+Work out the fixes as if today's requirements had been known from the start. Look for the
+one fix behind several problems. Write each fix above the problems it solves:
+
+```md
+- Extract a `PaymentProvider` interface that Stripe and PayPal implement, so checkout and
+  refunds stop knowing which one runs.
+  - `checkout/submit.ts:9` imports `payments/stripe.ts` directly.
+  - `refunds/refund.ts:22` wraps every Stripe call in `if (order.provider === "paypal")`.
+```
+
+## 6. Fix in small steps
+
+One fix group per commit. Run the suite after each; a red run is fixed or reverted before the
+next step. Behaviour stays the same: never weaken a test, raise a timeout or add a
+suppression to get green. Remove the special cases the redesign made unnecessary and keep
+the ones the system still needs.
+
+With the extras chosen, do them last, after the code is settled: delete comments that only
+restate the implementation (keep comments about something outside the code), and remove
+tests that repeat the implementation or cannot fail.
+
+## 7. Check and repeat
+
+Start a fresh read-only reviewer subagent (two when the repo is large, split by folder) with
+the log, the diff and the problem lenses; it reports problems still worth fixing. When the
+host has no subagents, re-read the diff yourself against the lenses and say so in the log.
+Fix what is real and repeat. Done when:
+
+- the full suite is green and matches or beats the baseline;
+- every touched module has unit tests;
+- a typical change lands in one place;
+- no import points at something more volatile than itself;
+- the reviewer finds nothing worth fixing;
+- behaviour is unchanged, apart from bugs the refactor fixed and logged.
+
+## 8. Ship
+
+Follow `principle-ship`: PR, self-review, green CI, merge, confirm the deploy. In the log
+write `Shipped: <PR>` (or `Committed:` with no remote, per the contract). Tell the user the
+log path and the before and after counts: special cases, duplicated blocks, untested
+modules, tests added.
+
+## Tips
+
+- Script away function bodies (a skeleton) so the whole repo fits in context.
+- Have subagents summarise folders so you can reason across all of it.
+- Script an import graph and rerun it as you go.
+- Use `git log --name-only` to see which files change together; that is the evidence for
+  hidden links.
+- Keep the log current; it survives a context compaction.

skills/dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dev
-description: Entry point for the RayStack development flow. Use for "/dev", "/raystack new project", "/raystack project new", "/raystack project update", "/raystack project gaps", "/raystack project review", "/raystack project migrate", "start a new project", "plan this feature", "build this", "fix this bug properly", "where are we", or any request to take work from idea to shipped code.
+description: Entry point for the RayStack development flow. Use for "/dev", "/raystack new project", "/raystack project new", "/raystack project update", "/raystack project gaps", "/raystack project review", "/raystack project migrate", "/raystack project refactor", "start a new project", "plan this feature", "build this", "fix this bug properly", "where are we", or any request to take work from idea to shipped code.
 ---
 
 # Dev
@@ -26,6 +26,7 @@ a step, by saying so.
 | `dev-gaps` | Finds and fills missing documents in an existing project |
 | `dev-review` | Read-only review of architecture, specs and plan against the code |
 | `dev-migrate` | Moves part of a project to another stack, step by step |
+| `dev-refactor` | Refactors a codebase inside its own architecture, tests first, DRY and SOLID |
 
 **Project commands** (`/raystack project <verb>`, or `new project`) go straight to:
 
@@ -35,6 +36,7 @@ a step, by saying so.
 | `update`, `gaps` | `dev-gaps` |
 | `review` | `dev-review` |
 | `migrate` | `dev-migrate` |
+| `refactor` | `dev-refactor` |
 
 ## 1. Detect state