@jstn-sdk/rcs 0.1.0

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

@@ -0,0 +1,300 @@
+---
+name: security-review
+description: Run a comprehensive security review on code
+---
+
+# Security Review Skill
+
+Conduct a thorough security audit checking for OWASP Top 10 vulnerabilities, hardcoded secrets, and unsafe patterns.
+
+## When to Use
+
+This skill activates when:
+- User requests "security review", "security audit"
+- After writing code that handles user input
+- After adding new API endpoints
+- After modifying authentication/authorization logic
+- Before deploying to production
+- After adding external dependencies
+
+## What It Does
+
+## GPT-5.5 Guidance Alignment
+
+- Default to outcome-first progress and completion reporting: state the target result, evidence, validation status, 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 correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the security review is grounded; stop once enough evidence exists.
+- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, credentialed, external-production, or preference-dependent.
+
+Delegates to the `security-reviewer` agent (THOROUGH tier) for deep security analysis:
+
+1. **OWASP Top 10 Scan**
+   - A01: Broken Access Control
+   - A02: Cryptographic Failures
+   - A03: Injection (SQL, NoSQL, Command, XSS)
+   - A04: Insecure Design
+   - A05: Security Misconfiguration
+   - A06: Vulnerable and Outdated Components
+   - A07: Identification and Authentication Failures
+   - A08: Software and Data Integrity Failures
+   - A09: Security Logging and Monitoring Failures
+   - A10: Server-Side Request Forgery (SSRF)
+
+2. **Secrets Detection**
+   - Hardcoded API keys
+   - Passwords in source code
+   - Private keys in repo
+   - Tokens and credentials
+   - Connection strings with secrets
+
+3. **Input Validation**
+   - All user inputs sanitized
+   - SQL/NoSQL injection prevention
+   - Command injection prevention
+   - XSS prevention (output escaping)
+   - Path traversal prevention
+
+4. **Authentication/Authorization**
+   - Proper password hashing (bcrypt, argon2)
+   - Session management security
+   - Access control enforcement
+   - JWT implementation security
+
+5. **Dependency Security**
+   - Run `npm audit` for known vulnerabilities
+   - Check for outdated dependencies
+   - Identify high-severity CVEs
+
+## Agent Delegation
+
+```
+delegate(
+  role="security-reviewer",
+  tier="THOROUGH",
+  prompt="SECURITY REVIEW TASK
+
+Conduct comprehensive security audit of codebase.
+
+Scope: [specific files or entire codebase]
+
+Security Checklist:
+1. OWASP Top 10 scan
+2. Hardcoded secrets detection
+3. Input validation review
+4. Authentication/authorization review
+5. Dependency vulnerability scan (npm audit)
+
+Output: Security review report with:
+- Summary of findings by severity (CRITICAL, HIGH, MEDIUM, LOW)
+- Specific file:line locations
+- CVE references where applicable
+- Remediation guidance for each issue
+- Overall security posture assessment"
+)
+```
+
+## External Model Consultation (Preferred)
+
+The security-reviewer agent SHOULD consult Codex for cross-validation.
+
+### Protocol
+1. **Form your OWN security analysis FIRST** - Complete the review independently
+2. **Consult for validation** - Cross-check findings with Codex
+3. **Critically evaluate** - Never blindly adopt external findings
+4. **Graceful fallback** - Never block if tools unavailable
+
+### When to Consult
+- Authentication/authorization code
+- Cryptographic implementations
+- Input validation for untrusted data
+- High-risk vulnerability patterns
+- Production deployment code
+
+### When to Skip
+- Low-risk utility code
+- Well-audited patterns
+- Time-critical security assessments
+- Code with existing security tests
+
+### Tool Usage
+Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools.
+Use `mcp__x__ask_codex` with `agent_role: "security-reviewer"`.
+If ToolSearch finds no MCP tools, fall back to the `security-reviewer` agent.
+
+**Note:** Security second opinions are high-value. Consider consulting for CRITICAL/HIGH findings.
+
+## Output Format
+
+```
+SECURITY REVIEW REPORT
+======================
+
+Scope: Entire codebase (42 files scanned)
+Scan Date: 2026-01-24T14:30:00Z
+
+CRITICAL (2)
+------------
+1. src/api/auth.ts:89 - Hardcoded API Key
+   Finding: AWS API key hardcoded in source code
+   Impact: Credential exposure if code is public or leaked
+   Remediation: Move to environment variables, rotate key immediately
+   Reference: OWASP A02:2021 – Cryptographic Failures
+
+2. src/db/query.ts:45 - SQL Injection Vulnerability
+   Finding: User input concatenated directly into SQL query
+   Impact: Attacker can execute arbitrary SQL commands
+   Remediation: Use parameterized queries or ORM
+   Reference: OWASP A03:2021 – Injection
+
+HIGH (5)
+--------
+3. src/auth/password.ts:22 - Weak Password Hashing
+   Finding: Passwords hashed with MD5 (cryptographically broken)
+   Impact: Passwords can be reversed via rainbow tables
+   Remediation: Use bcrypt or argon2 with appropriate work factor
+   Reference: OWASP A02:2021 – Cryptographic Failures
+
+4. src/components/UserInput.tsx:67 - XSS Vulnerability
+   Finding: User input rendered with dangerouslySetInnerHTML
+   Impact: Cross-site scripting attack vector
+   Remediation: Sanitize HTML or use safe rendering
+   Reference: OWASP A03:2021 – Injection (XSS)
+
+5. src/api/upload.ts:34 - Path Traversal Vulnerability
+   Finding: User-controlled filename used without validation
+   Impact: Attacker can read/write arbitrary files
+   Remediation: Validate and sanitize filenames, use allowlist
+   Reference: OWASP A01:2021 – Broken Access Control
+
+...
+
+MEDIUM (8)
+----------
+...
+
+LOW (12)
+--------
+...
+
+DEPENDENCY VULNERABILITIES
+--------------------------
+Found 3 vulnerabilities via npm audit:
+
+CRITICAL: axios@0.21.0 - Server-Side Request Forgery (CVE-2021-3749)
+  Installed: axios@0.21.0
+  Fix: npm install axios@0.21.2
+
+HIGH: lodash@4.17.19 - Prototype Pollution (CVE-2020-8203)
+  Installed: lodash@4.17.19
+  Fix: npm install lodash@4.17.21
+
+...
+
+OVERALL ASSESSMENT
+------------------
+Security Posture: POOR (2 CRITICAL, 5 HIGH issues)
+
+Immediate Actions Required:
+1. Rotate exposed AWS API key
+2. Fix SQL injection in db/query.ts
+3. Upgrade password hashing to bcrypt
+4. Update vulnerable dependencies
+
+Recommendation: DO NOT DEPLOY until CRITICAL and HIGH issues resolved.
+```
+
+## Security Checklist
+
+The security-reviewer agent verifies:
+
+### Authentication & Authorization
+- [ ] Passwords hashed with strong algorithm (bcrypt/argon2)
+- [ ] Session tokens cryptographically random
+- [ ] JWT tokens properly signed and validated
+- [ ] Access control enforced on all protected resources
+- [ ] No authentication bypass vulnerabilities
+
+### Input Validation
+- [ ] All user inputs validated and sanitized
+- [ ] SQL queries use parameterization (no string concatenation)
+- [ ] NoSQL queries prevent injection
+- [ ] File uploads validated (type, size, content)
+- [ ] URLs validated to prevent SSRF
+
+### Output Encoding
+- [ ] HTML output escaped to prevent XSS
+- [ ] JSON responses properly encoded
+- [ ] No user data in error messages
+- [ ] Content-Security-Policy headers set
+
+### Secrets Management
+- [ ] No hardcoded API keys
+- [ ] No passwords in source code
+- [ ] No private keys in repo
+- [ ] Environment variables used for secrets
+- [ ] Secrets not logged or exposed in errors
+
+### Cryptography
+- [ ] Strong algorithms used (AES-256, RSA-2048+)
+- [ ] Proper key management
+- [ ] Random number generation cryptographically secure
+- [ ] TLS/HTTPS enforced for sensitive data
+
+### Dependencies
+- [ ] No known vulnerabilities in dependencies
+- [ ] Dependencies up to date
+- [ ] No CRITICAL or HIGH CVEs
+- [ ] Dependency sources verified
+
+## Severity Definitions
+
+**CRITICAL** - Exploitable vulnerability with severe impact (data breach, RCE, credential theft)
+**HIGH** - Vulnerability requiring specific conditions but serious impact
+**MEDIUM** - Security weakness with limited impact or difficult exploitation
+**LOW** - Best practice violation or minor security concern
+
+## Remediation Priority
+
+1. **Rotate exposed secrets** - Immediate (within 1 hour)
+2. **Fix CRITICAL** - Urgent (within 24 hours)
+3. **Fix HIGH** - Important (within 1 week)
+4. **Fix MEDIUM** - Planned (within 1 month)
+5. **Fix LOW** - Backlog (when convenient)
+
+
+## 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.
+
+## Use with Other Skills
+
+**With Team:**
+```
+/team "run security review on authentication module"
+```
+Uses: explore → security-reviewer → executor → security-reviewer (re-verify)
+
+**With Swarm:**
+```
+/swarm 4:security-reviewer "audit all API endpoints"
+```
+Parallel security review across multiple endpoints.
+
+**With Ralph:**
+```
+/ralph security-review then fix all issues
+```
+Review, fix, re-review until all issues resolved.
+
+## Best Practices
+
+- **Review early** - Security by design, not afterthought
+- **Review often** - Every major feature or API change
+- **Automate** - Run security scans in CI/CD pipeline
+- **Fix immediately** - Don't accumulate security debt
+- **Educate** - Learn from findings to prevent future issues
+- **Verify fixes** - Re-run security review after remediation