RayStack is a skill pack for coding agents that builds and reviews software. Type /raystack
in a repo and it works out what you want: take a product from idea to shipped code with
reviewed builds, or get a ranked findings report on cost, security, bottlenecks, deploys,
scaling or the database, with evidence for every finding and a fix you apply yourself. It's how
I build and what I check when I audit someone's stack, written down as agent skills.
By Harun R. Rayhan (harun.dev, @harundotdev). Product page: harun.dev/raystack.
bashandjq. The guard needsjqto read each command; without it, it blocks every shell command during a review (fails closed).- For PDF export: Chrome or Chromium, and
npx(Node.js).
git clone --depth 1 https://github.com/HarunRRayhan/RayStack.git ~/.raystack && ~/.raystack/install.shThis clones RayStack to ~/.raystack and copies all twenty-three skills into ~/.claude/skills.
For another agent add --agent codex, --agent cursor or --agent grok. To update, run
git -C ~/.raystack pull && ~/.raystack/install.sh. --uninstall removes them again.
Or use the skills CLI: npx skills add HarunRRayhan/RayStack -g -a claude-code.
The per-agent options below do the same thing in each agent's own way.
/plugin marketplace add HarunRRayhan/RayStack
/plugin install raystack@raystack
From a terminal it's claude plugin marketplace add HarunRRayhan/RayStack and
claude plugin install raystack@raystack. To try a checkout for one session:
claude --plugin-dir /path/to/raystack.
As a plugin, the skills are namespaced: raystack:raystack, raystack:aws-billing-review and
so on. /raystack still finds the router (it resolves to /raystack:raystack); name a single
review with its full name, e.g. /raystack:aws-billing-review. With ./install.sh --agent claude
the skills are personal skills and keep their bare names (/raystack, /aws-billing-review).
codex plugin marketplace add HarunRRayhan/RayStack
codex plugin add raystack@raystackCodex reads this repo's .claude-plugin/marketplace.json. Without a plugin,
./install.sh --agent codex copies the skills to ~/.agents/skills/.
Add the repo as a git marketplace with cursor-agent plugin marketplace add <gitUrl>, or try it
for one session with cursor-agent --plugin-dir /path/to/raystack. Whether a git marketplace
picks up the .claude-plugin/ files is unverified. If it doesn't,
./install.sh --agent cursor copies the skills to ~/.cursor/skills/.
grok plugin marketplace add HarunRRayhan/RayStack
grok plugin install raystack --trustgrok plugin validate . passes on this repo, but these two commands are unverified end to
end. Grok also scans ~/.claude/skills/ and ~/.cursor/skills/, so install.sh covers it.
Clone the repo and copy (or --link) the skills into your agent's skills folder:
./install.sh --agent <claude|cursor|codex|grok|opencode>
./install.sh --agent custom --dir /path/to/skills--dry-run shows what it would do and --uninstall removes exactly the twenty-three RayStack skills.
Per-agent details and sources are in docs/agents.md.
Type /raystack in the repo you want reviewed. It looks at the file names (Terraform,
railway.json, migrations and so on), recommends reviews, and asks you once which ones to run
and whether it may make read-only live calls. Then it runs them one at a time.
Or skip the router and name a review: "run database-review", /raystack:aws-billing-review
(plugin) or /aws-billing-review (install.sh), or just "why is my AWS bill so high".
| Skill | What it reviews |
|---|---|
raystack |
Entry point. Picks the reviews for this repo and runs them. |
aws-billing-review |
AWS spend, with ranked savings in $/mo |
aws-security-review |
IAM, public exposure, logging and secrets on AWS |
aws-bottleneck-review |
Throttling, limits, quotas and single points on the AWS request path |
infra-review |
Deploys, rollback, backups, monitoring and exposure on any platform |
scaling-review |
What breaks first at 10x and 100x load |
database-review |
Queries, indexes, migrations, backups, connections and bloat |
app-security-review |
App code: authz, injection, secrets, sessions, dependency risk. Code only, never calls a running app. Dependency audits run only with your live consent; without it, the review lists the commands for you to run |
performance-review |
App speed: N+1 queries, hot paths, blocking calls, caching, payload and bundle weight |
pipeline-security-review |
CI/CD pipelines: workflow permissions, untrusted input, pinned actions, Dockerfile and supply chain |
With no live access, a review still works from your IaC and code. It marks those findings
(unconfirmed) and lists the exports or commands it needs from you.
/raystack scan <type> runs a set of reviews as one job, with one consent call for live
access, network scanners and targets. Reviews with no signals in the repo are listed as skipped.
| Type | Runs |
|---|---|
security |
app-security-review, pipeline-security-review, aws-security-review, infra-review |
performance |
performance-review, database-review, aws-bottleneck-review |
scalability |
scaling-review, database-review |
infra |
infra-review, pipeline-security-review, aws-security-review, aws-bottleneck-review |
aws |
aws-billing-review, aws-security-review, aws-bottleneck-review |
database |
database-review |
all |
every review above whose signals are found |
When 2 or more reviews run, reviews/YYYY-MM-DD-scan-<type>.md merges them: one ranked list,
duplicates merged, with a table of what ran and what was skipped.
Scanners (gitleaks, semgrep, osv-scanner, zizmor, actionlint, hadolint) are used when
installed and never installed by RayStack: brew install gitleaks semgrep osv-scanner zizmor actionlint hadolint.
No review changes anything live. Fixes come back as diffs or as commands for you to run.
Each review turns on a guard hook (skills/raystack/hooks/readonly-guard.sh) that checks every
shell command before it runs. Only the CLIs it lists are checked: aws, gcloud, az,
kubectl, oc, gh, terraform, tofu, terragrunt, helm, railway, wrangler, redis-cli
and the SQL clients get read verbs only, one SQL read per call with no SQL comments. Deploy tools
such as pulumi, cdk, serverless, fly, vercel or heroku are blocked outright, as are
pg_dump and pg_restore, and commands that print secret values or credentials (for example
terraform show, helm get values, aws ecr get-login-password). A name counts even inside a
hyphenated or slashed word (aws-cdk, amazon/aws-cli). Package runners (npx, bunx, uvx),
shells (bash, sh -c, env), ssh and most npm, yarn and docker subcommands are
blocked during a review; only a short list of reads such as docker ps, docker logs --tail 200 and npm ls gets through. Dependency audits are the one package-manager exception, in
forms that run no repo code: npm audit, composer audit --no-plugins --no-scripts,
bundle-audit check, and pip-audit (with -r, also --disable-pip and --no-deps or
--require-hashes), with read flags only and no fix. They run only with your live consent;
without it, the review lists the commands for you to run. Reads that return env vars or user data
(Lambda configs, ECS task definitions, launch templates) are left for you to run. The six
scanners (gitleaks, semgrep, osv-scanner, zizmor, actionlint, hadolint) are checked
too and run only in the read forms in skills/raystack/references/scanners.md; gh runs on
your GitHub token, so it gets a read allow-list.
Everything else is not checked: other tools, the agent's own file Read tool, and scripts in
the repo (a make target can do anything). The guard is a seatbelt, not a
sandbox, and it only switches on by itself in Claude Code. In Cursor, Codex and Grok the
reviews follow the same rules but nothing enforces them. Either way, run reviews with read-only
credentials (AWS ReadOnlyAccess or ViewOnlyAccess, a read-only DB role). Those are the real
boundary. No read-only AWS profile yet? The aws-readonly-setup skill makes one for you: it
signs you in through the browser with aws login, creates a raystack-readonly role with
ReadOnlyAccess minus data reads (S3 objects, secrets, SSM parameters), and proves it can
read config but not data or writes. It asks before that one IAM change and
creates no access keys. The full rules are in the review contract.
In Claude Code, once a review starts the guard stays on for the rest of the session. It then
also blocks $, backslashes, unquoted globs (*, ?, [ ]) and redirects (>, <) in any
shell command, not only cloud ones. It also blocks any command that mentions a shell, env,
ssh or scp, a package runner (npx, uv run, npm test or other scripts, yarn, pnpm
and bun except --version), a container lifecycle command (docker compose up, docker run),
a docker flag before the subcommand, or a monitored tool's name anywhere (so grep -n npm Dockerfile and grep -rn "@aws-sdk" . are blocked too). Start a new session after a review.
Each review writes reviews/YYYY-MM-DD-<skill>.md in your repo: an executive summary, the
inputs it used and the ones it lacked, findings ranked Critical to Low with evidence, a fix and an
estimated $/mo where one can be worked out, then a "Commands for you to run" section. The layout
is in report-template.md.
Want a PDF for a client or your boss? The review offers one at the end, via
skills/raystack/scripts/report-pdf.sh (needs Chrome or Chromium and npx). Raw HTML in a
report is shown as text, not rendered.
RayStack also ships four principle skills and the local-verify playbook. They aren't reviews.
Each principle is a short rule, and local-verify is a step-by-step playbook. Your agent picks
them up by itself when the task fits, and /raystack never runs them.
| Skill | The rule |
|---|---|
principle-ship |
Done means live: PR, self-review, green CI, merge, deploy confirmed |
principle-smallest-change |
The smallest change that solves the whole task, finished everywhere it reaches |
principle-ask-with-question-tool |
Ask through the agent's question tool, batched, recommended option first |
principle-secrets-layout |
Real values in gitignored .secrets/<service>.env, committed .example templates, never print a value |
local-verify |
Check a user-facing change in a real local browser. principle-ship calls it. Never touches .env, production data, live payments or real email |
principle-ship reads .raystack.json at the repo root, or ~/.raystack.json if the repo has
none:
{ "ship": { "autoMerge": false, "deployCheck": "Deploy workflow on main, then GET /health" } }With autoMerge off (the default), the agent stops at green CI and asks before it merges. Turn
it on and it merges on green, then waits for the deploy. deployCheck tells it how to confirm
the deploy is live: a workflow name, a URL or a health check.
RayStack also carries a development flow, from research to a shipped build. Type /raystack and pick
"Build something", say "start a new project" or "build this", or call /dev directly. It picks a track by size:
- Quick: a bug or small change. No PRD. Fix it, test it, ship it.
- Standard: one slice of work. Spec if missing, then a plan, then a reviewed build.
- Full: a new product. Project layout, research, PRD, specs, plan, build.
Decisions land in DECISIONS.md and are never asked twice. The build keeps a ledger, so a
stopped run can resume.
| Skill | What it does |
|---|---|
dev |
Entry point. Picks Quick, Standard or Full and runs the right skills. |
dev-hub |
Sets up AGENTS.md, DECISIONS.md and the docs folders, in one repo or a code-free hub |
dev-research |
Dated research notes with a source beside every fact |
dev-prd |
Interviews you, then writes the PRD with goals, non-goals and a behaviour contract |
dev-spec |
Architecture and per-area tech specs from the PRD (on Standard with no PRD, it writes the slice's ## Behaviours B-IDs), plus the default principles |
dev-plan |
A plan for one slice, checked for gaps before the build starts |
dev-build |
Builds the plan task by task with a fresh implementer and reviewer for each |
RayStack borrows ideas from four skill packs:
- pstack: short principle skills and step-by-step playbooks.
- mattpocock/skills: plain, composable skills.
- gstack: multi-agent installs, review skills and safety hooks that only switch on while their skill runs.
- Ponytail: the smallest complete change, and
shortcut:comments for known limits.
MIT. See LICENSE.
Made by Harun R. Rayhan (@harundotdev). For a hands-on audit of your stack: harun.dev/consultation.