supipowers 1.3.0 → 1.5.1

package/skills/code-review/SKILL.md

@@ -3,43 +3,140 @@ name: code-review
 description: Deep code review methodology for thorough quality assessment
 ---
 
-# Code Review Skill
-
-Systematic approach to reviewing code changes.
-
-## Review Checklist
-
-### Correctness
-- Does the code do what it claims?
-- Are edge cases handled?
-- Are error conditions handled?
-
-### Security
-- Input validation at system boundaries?
-- SQL injection, XSS, command injection risks?
-- Secrets in code or logs?
-- Authentication/authorization checks?
-
-### Performance
-- Unnecessary loops or allocations?
-- N+1 query patterns?
-- Missing indexes for frequent queries?
-- Large payloads or unbounded lists?
-
-### Maintainability
-- Clear naming (functions, variables, files)?
-- Single responsibility per unit?
-- Unnecessary abstractions or premature optimization?
-- Comments where logic isn't self-evident?
-
-### Testing
-- Tests cover the happy path?
-- Tests cover error/edge cases?
-- Tests are deterministic (no flaky tests)?
-- Test names describe the behavior?
-
-## Severity Levels
-
-- **error**: Must fix before merge. Bugs, security issues, data loss risks.
-- **warning**: Should fix. Code quality, maintainability, minor issues.
-- **info**: Nice to have. Style, naming suggestions, minor improvements.
+# Code Review
+
+Identify defects, security risks, and maintainability problems in code changes before they merge.
+
+## Quick Reference
+
+| Aspect | Detail |
+|---|---|
+| **Input** | PR diff, file contents, PR title/description |
+| **Output** | Structured findings (see Finding Format below) |
+| **Scope** | Changed lines + immediate context; follow references 1 level deep when a change touches a public API |
+| **Skip** | Formatting, import order, whitespace — defer to linters |
+| **Depth** | Read every changed line; skim unchanged context for broken assumptions |
+
+## Finding Format
+
+Each finding MUST follow this structure:
+
+```
+**[severity]** `file:line` — Description of the issue.
+Suggestion: concrete fix or direction.
+```
+
+**Severity levels:**
+
+| Level | Meaning | Gate |
+|---|---|---|
+| `error` | Bugs, security holes, data loss, crashes | MUST fix before merge |
+| `warning` | Wrong abstraction, missing validation, performance trap | SHOULD fix |
+| `info` | Naming, style, minor simplification | Nice to have |
+
+## Review Procedure
+
+Execute these phases in order. Each phase produces findings or nothing.
+
+### Phase 1 — Understand Intent
+Read the PR title, description, and linked issues. Determine what the change is supposed to do. If intent is unclear, report as `warning` before proceeding.
+
+### Phase 2 — Correctness
+For each changed function/block:
+- Trace inputs through the logic. Identify domain boundaries (null, empty, zero, negative, max-length).
+- For each boundary, verify the code handles or explicitly rejects it. Unhandled → `error`.
+- Check return values: can a caller confuse a failure return with a success? Silent failures → `error`.
+
+### Phase 3 — Security
+At every system boundary (user input, HTTP params, DB queries, shell commands, file paths):
+- Verify input is validated or sanitized before use. Missing → `error`.
+- Check for secrets in code, logs, or error messages. Present → `error`.
+- Verify auth checks exist for protected operations. Missing → `error`.
+
+### Phase 4 — Performance
+- Identify loops over collections: is work inside the loop that could be batched or hoisted? Report as `warning`.
+- Look for N+1 patterns: a query inside a loop that iterates query results. Report as `warning`.
+- Flag unbounded lists or payloads with no pagination/limit. Report as `warning`.
+
+### Phase 5 — Maintainability
+- Flag functions doing more than one job (needs "and" to describe) → `warning`.
+- Flag duplicated logic across the diff (same pattern 2+ times) → `info`.
+- Flag misleading names (function name promises X, body does Y) → `warning`.
+
+### Phase 6 — Tests
+- If the change adds behavior, verify a test covers the happy path. Missing → `warning`.
+- If the change fixes a bug, verify a regression test exists. Missing → `warning`.
+- Flag non-deterministic tests (time-dependent, random, order-dependent) → `warning`.
+
+## Examples
+
+### Bug: unhandled null at domain boundary
+
+```ts
+// PR diff
+function getUser(id: string) {
+  const row = db.query("SELECT * FROM users WHERE id = ?", [id]);
+  return { name: row.name, email: row.email };
+}
+```
+
+**Finding:**
+```
+**[error]** `src/users.ts:3` — `db.query` returns `null` when no row matches,
+but the next line unconditionally accesses `.name` on the result.
+Suggestion: Guard with `if (!row) return null` or throw a NotFoundError.
+```
+
+### Security: unsanitized input in shell command
+
+```python
+# PR diff
+def export_report(filename):
+    os.system(f"tar czf /tmp/{filename}.tar.gz /data/reports")
+```
+
+**Finding:**
+```
+**[error]** `reports/export.py:3` — `filename` is interpolated into a shell
+command without sanitization. An attacker passing `; rm -rf /` exploits this.
+Suggestion: Use `subprocess.run(["tar", "czf", ...])` with a list to avoid shell injection,
+and validate `filename` against an allowlist pattern.
+```
+
+### N+1 query in loop
+
+```ts
+// PR diff
+const orders = await db.orders.findMany({ where: { status: "open" } });
+for (const order of orders) {
+  const customer = await db.customers.findUnique({ where: { id: order.customerId } });
+  order.customerName = customer.name;
+}
+```
+
+**Finding:**
+```
+**[warning]** `src/orders.ts:2-5` — Each loop iteration issues a separate
+DB query for the customer. With N open orders this is N+1 queries.
+Suggestion: Use `include: { customer: true }` in the initial query, or
+batch-fetch customers with `findMany({ where: { id: { in: customerIds } } })`.
+```
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---|---|
+| Report every finding with file, line, severity, and suggestion | Report vague findings without location or fix direction |
+| Prioritize errors first, then warnings, then info | Bury a critical bug under 10 style nits |
+| Read the full diff before writing findings | Review only the first file and stop |
+| Verify claims by reading the referenced code | Assume a pattern is wrong without checking the implementation |
+| Limit info-level findings to 5 max | Flood the review with cosmetic suggestions |
+
+## Final Checklist
+
+Before submitting your review, verify:
+- [ ] Every `error` finding includes a concrete reproduction scenario or input
+- [ ] Every finding has `file:line`, severity, description, and suggestion
+- [ ] Findings are grouped by severity (errors first)
+- [ ] No duplicate findings (same root cause reported once, not per-occurrence)
+- [ ] If zero findings: explicitly state "No issues found" — do not return empty output

package/skills/context-mode/SKILL.md

@@ -1,73 +1,88 @@
-# context-mode — MANDATORY routing rules
+# supi-context-mode
 
-You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.
+Route high-output tool calls through sandboxed execution to protect the context window.
 
-## BLOCKED commands — do NOT attempt these
+| Scope | Tool routing rules for supi-context-mode |
+|-------|-----------------------------------------------------|
+| Trigger | Always active when supi-context-mode tools are available |
+| Goal | Prevent context flooding — a single unrouted command can dump 56 KB into context |
+| Key rule | Blocked tools return errors; use sandbox equivalents instead |
 
-### curl / wget — BLOCKED
-Any Bash command containing `curl` or `wget` is intercepted and replaced with an error message. Do NOT retry.
-Instead use:
-- `ctx_fetch_and_index(url, source)` to fetch and index web pages
-- `ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
+## Tool Selection Hierarchy
 
-### Inline HTTP — BLOCKED
-Any Bash command containing `fetch('http`, `requests.get(`, `requests.post(`, `http.get(`, or `http.request(` is intercepted and replaced with an error message. Do NOT retry with Bash.
-Instead use:
-- `ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
+Pick the highest-priority tool that fits the task:
 
-### WebFetch / Fetch — BLOCKED
-WebFetch and Fetch calls are denied entirely.
-Instead use:
-- `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` to query the indexed content
+| Priority | Tool | Use for |
+|----------|------|---------|
+| 1 — GATHER | `ctx_batch_execute(commands, queries)` | Primary tool. Runs all commands, auto-indexes, returns search results. ONE call replaces 30+ individual calls. |
+| 2 — FOLLOW-UP | `ctx_search(queries: ["q1", "q2", ...])` | Query already-indexed content. Pass ALL questions as array in ONE call. |
+| 3 — PROCESSING | `ctx_execute(language, code)` / `ctx_execute_file(path, language, code)` | Sandbox execution. Only stdout enters context. |
+| 4 — WEB | `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` | Fetch, chunk, index, query. Raw HTML never enters context. |
+| 5 — INDEX | `ctx_index(content, source)` | Store content in FTS5 knowledge base for later search. |
 
-### Grep — BLOCKED
-Grep calls are intercepted and blocked. Do NOT retry with Grep.
-Instead use:
-- `ctx_search(queries: ["<pattern>"])` to search indexed content
-- `ctx_batch_execute(commands, queries)` to run searches and return compressed results
-- `ctx_execute(language: "shell", code: "grep ...")` to run searches in sandbox
+## Blocked Commands
 
-### Find / Glob — BLOCKED
-Find/Glob calls are intercepted and blocked. Do NOT retry with Find/Glob.
-Instead use:
-- `ctx_execute(language: "shell", code: "find ...")` to run in sandbox
-- `ctx_batch_execute(commands, queries)` for multiple searches
+Blocked commands are intercepted and replaced with an error. Do NOT retry via Bash.
 
+| Blocked tool | Replacement |
+|---|---|
+| `curl` / `wget` in Bash | `ctx_fetch_and_index(url, source)` or `ctx_execute` with `fetch()` |
+| Inline HTTP (`fetch('http`, `requests.get(`, etc.) in Bash | `ctx_execute(language, code)` — only stdout enters context |
+| WebFetch / Fetch tool | `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` |
+| Grep tool | `ctx_search(queries)`, `ctx_batch_execute(commands, queries)`, or `ctx_execute(language: "shell", code: "grep ...")` |
+| Find / Glob tool | `ctx_execute(language: "shell", code: "find ...")` or `ctx_batch_execute(commands, queries)` |
 
-## REDIRECTED tools — use sandbox equivalents
+### Example: routing a grep call
 
-### Bash (>20 lines output)
-Bash is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands.
-For everything else, use:
-- `ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
-- `ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
+```
+// WRONG — blocked, returns error
+grep(pattern: "TODO", path: "src/")
 
-### Read (large files)
-Reads are never blocked — they always go through OMP's native read tool so hashline anchors (`N#XX`) are preserved for the edit contract. Large file reads (>110 lines) are automatically compressed to head (80 lines) + tail (30 lines) with a `sel` hint for the omitted section.
-For analysis-only reads where hashlines aren't needed, `ctx_execute_file(path, language, code)` remains more efficient — only your printed summary enters context.
+// CORRECT — runs in sandbox, only printed summary enters context
+ctx_execute(language: "shell", code: "grep -rn TODO src/")
 
-## Tool selection hierarchy
+// BEST — indexes output and returns search results in one call
+ctx_batch_execute(
+  commands: [{ label: "TODOs", command: "grep -rn TODO src/" }],
+  queries: ["TODO fixme priority"]
+)
+```
 
-1. **GATHER**: `ctx_batch_execute(commands, queries)` — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
-2. **FOLLOW-UP**: `ctx_search(queries: ["q1", "q2", ...])` — Query indexed content. Pass ALL questions as array in ONE call.
-3. **PROCESSING**: `ctx_execute(language, code)` | `ctx_execute_file(path, language, code)` — Sandbox execution. Only stdout enters context.
-4. **WEB**: `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` — Fetch, chunk, index, query. Raw HTML never enters context.
-5. **INDEX**: `ctx_index(content, source)` — Store content in FTS5 knowledge base for later search.
+## Redirected Tools
 
-## Subagent routing
+### Bash
 
-When spawning subagents (Agent/Task tool), the routing block is automatically injected into their prompt. Bash-type subagents are upgraded to general-purpose so they have access to MCP tools. You do NOT need to manually instruct subagents about context-mode.
+Bash is for commands producing <20 lines: `git`, `mkdir`, `rm`, `mv`, `ls`, `npm install`, `pip install`.
 
-## Output constraints
+For everything else:
+- `ctx_batch_execute(commands, queries)` — multiple commands + search in ONE call
+- `ctx_execute(language: "shell", code: "...")` — sandbox, only stdout enters context
 
-- Keep responses under 500 words.
-- Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
-- When indexing content, use descriptive source labels so others can `ctx_search(source: "label")` later.
+### Read
 
-## ctx commands
+Reads are never blocked — OMP's native read tool preserves hashline anchors (`N#XX`) for the edit contract. Large reads (>110 lines) are auto-compressed to head (80) + tail (30) with a `sel` hint.
+
+For analysis-only reads where anchors are not needed, prefer `ctx_execute_file(path, language, code)` — only your printed summary enters context.
+
+## Subagent Routing
+
+The routing block is automatically injected into subagent prompts. Bash-type subagents are upgraded to general-purpose for tool access. You do NOT need to manually instruct subagents about context-mode.
+
+## Output Constraints
+
+- Write artifacts (code, configs, PRDs) to files — never inline. Return only: file path + 1-line description.
+- When indexing, use descriptive `source` labels so others can `ctx_search(source: "label")` later.
+
+## `ctx` Commands
 
 | Command | Action |
 |---------|--------|
-| `ctx stats` | Call the `ctx_stats` MCP tool and display the full output verbatim |
-| `ctx doctor` | Call the `ctx_doctor` MCP tool, run the returned shell command, display as checklist |
-| `ctx upgrade` | Call the `ctx_upgrade` MCP tool, run the returned shell command, display as checklist |
+| `ctx stats` | Call the `ctx_stats` tool, display full output verbatim |
+| `ctx purge` | Call the `ctx_purge` tool to clear all indexed content |
+
+## Checklist
+
+- [ ] Used tool hierarchy (batch_execute > search > execute > fetch) — not raw Bash/Grep/Find
+- [ ] No blocked tool calls attempted
+- [ ] Artifacts written to files, not returned inline
+- [ ] Source labels are descriptive for later search

package/skills/creating-supi-agents/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: creating-supi-agents
+description: Interactive guide for creating a new supipowers review agent from scratch
+---
+
+# Creating a Review Agent
+
+Guide the user through creating a specialized code review agent for supipowers' multi-agent `/supi:review` pipeline.
+
+## Quick Reference
+
+| Aspect | Detail |
+|--------|--------|
+| **Input** | User's description of what the agent should review |
+| **Output** | Agent file saved to `.omp/agents/<agent-name>.md` |
+| **File format** | YAML frontmatter (`name`, `description`, `focus`) + prompt body + `{output_instructions}` |
+| **Hard constraint** | Prompt body **MUST** end with `{output_instructions}` on its own line — the pipeline replaces it with the output schema at review time |
+| **Process** | Goal → Research → Present → Refine → Save |
+
+## Agent File Format
+
+```markdown
+---
+name: <kebab-case-name>
+description: <one-line summary>
+focus: <comma-separated areas>
+---
+
+<prompt body>
+
+{output_instructions}
+```
+
+## Process
+
+### Step 1: Understand the Goal
+
+Ask what kind of reviewer the user wants. Common archetypes:
+
+| Archetype | Focus areas |
+|-----------|-------------|
+| Performance | algorithmic complexity, memory, caching, lazy loading |
+| Accessibility | ARIA, semantic HTML, screen reader support, WCAG |
+| API design | REST conventions, error contracts, versioning |
+| Test quality | coverage gaps, flaky patterns, missing edge cases |
+| Security | injection, auth, secrets, OWASP Top 10 |
+| Documentation | JSDoc, README accuracy, changelog updates |
+
+### Step 2: Research
+
+Research established checklists and best practices for the focus area (e.g., OWASP for security, WCAG for accessibility). Look for language/framework-specific patterns relevant to the user's stack.
+
+### Step 3: Present Overview
+
+Present a structured proposal:
+- **Name**: suggested kebab-case name
+- **Description**: one-line summary
+- **Focus areas**: comma-separated specializations
+- **Review criteria**: bulleted list of what the agent will check
+- **Example findings**: 2–3 examples of what this agent would flag
+
+### Step 4: Refine with User
+
+Ask if they want to adjust:
+- Focus areas or review criteria
+- Tone — **strict** (flags aggressively, treats ambiguity as an issue) vs. **advisory** (flags only clear problems, uses softer language)
+- Project-specific conventions to enforce
+
+Iterate until the user approves.
+
+### Step 5: Save the Agent
+
+Generate the final agent file and save to `.omp/agents/<agent-name>.md`.
+
+## Agent Prompt Guidelines
+
+### What makes a good agent prompt
+
+1. **State the role** clearly (e.g., "You are a performance-focused code reviewer")
+2. **List specific check items** as concrete, actionable criteria (not vague categories)
+3. **Provide severity guidance** — define what warrants `error` vs. `warning` vs. `info`
+4. **Define scope boundaries** — state what is NOT in scope to prevent overlap with other agents
+5. **End with `{output_instructions}`** — mandatory, on its own line
+
+### Before / After: Check Item Quality
+
+```markdown
+# BEFORE — vague
+## What to Check
+- Look for performance issues
+- Check if things could be faster
+- Make sure the code is efficient
+
+# AFTER — concrete and actionable
+## What to Check
+- **Algorithmic complexity**: O(n²) or worse loops, unnecessary nested iterations
+- **Memory allocation**: Large object creation in hot paths, missing cleanup
+- **Caching opportunities**: Repeated expensive computations that could be memoized
+```
+
+### Before / After: Severity Guidance
+
+```markdown
+# BEFORE — missing severity
+Flag any issues you find in the code.
+
+# AFTER — calibrated severity
+## Severity Guide
+- **error**: Will cause visible degradation in production (e.g., O(n²) on large datasets)
+- **warning**: Potential issue that depends on scale (e.g., missing memoization)
+- **info**: Optimization opportunity, not a current problem
+```
+
+## Example: Performance Agent
+
+```markdown
+---
+name: performance
+description: Reviews code for performance issues and optimization opportunities
+focus: algorithmic complexity, memory allocation, caching, lazy loading
+---
+
+You are a performance-focused code reviewer. Analyze the provided code diff for performance issues.
+
+## What to Check
+
+- **Algorithmic complexity**: O(n²) or worse loops, unnecessary nested iterations
+- **Memory allocation**: Large object creation in hot paths, missing cleanup
+- **Caching opportunities**: Repeated expensive computations that could be memoized
+- **Lazy loading**: Resources loaded eagerly that could be deferred
+- **Bundle size**: Unnecessary imports, tree-shaking blockers
+- **Database queries**: N+1 queries, missing indexes, unbounded result sets
+
+## Severity Guide
+
+- **error**: Will cause visible performance degradation in production (e.g., O(n²) on large datasets)
+- **warning**: Potential issue that depends on scale (e.g., missing memoization)
+- **info**: Optimization opportunity, not a current problem
+
+## Out of Scope
+
+- Correctness issues (handled by correctness agent)
+- Style/formatting (handled by linter)
+- Security concerns (handled by security agent)
+
+{output_instructions}
+```
+
+## Example: Accessibility Agent
+
+```markdown
+---
+name: accessibility
+description: Reviews UI code for accessibility violations and WCAG compliance
+focus: ARIA attributes, semantic HTML, keyboard navigation, color contrast
+---
+
+You are an accessibility-focused code reviewer. Analyze the provided code diff for accessibility issues using WCAG 2.1 AA as the baseline.
+
+## What to Check
+
+- **Semantic HTML**: `<div>` or `<span>` used where `<button>`, `<nav>`, `<main>`, `<section>` belongs
+- **ARIA attributes**: Missing `aria-label` on icon-only buttons, incorrect `role` values
+- **Keyboard navigation**: Interactive elements not reachable via Tab, missing focus indicators
+- **Color contrast**: Text/background combinations below 4.5:1 ratio (normal text) or 3:1 (large text)
+- **Form labels**: Inputs without associated `<label>` or `aria-labelledby`
+- **Image alt text**: Missing or non-descriptive `alt` attributes on `<img>` tags
+
+## Severity Guide
+
+- **error**: Blocks assistive technology users entirely (e.g., button with no accessible name)
+- **warning**: Degraded experience for assistive technology users (e.g., missing focus indicator)
+- **info**: Best-practice improvement (e.g., prefer `<nav>` over `<div role="navigation">`)
+
+## Out of Scope
+
+- Visual design preferences (handled by design review)
+- Performance (handled by performance agent)
+- Business logic correctness (handled by correctness agent)
+
+{output_instructions}
+```
+
+## MUST DO / MUST NOT DO
+
+| MUST DO | MUST NOT DO |
+|---------|-------------|
+| End every agent prompt with `{output_instructions}` on its own line | Omit `{output_instructions}` — the pipeline will fail |
+| Include a severity guide (`error` / `warning` / `info`) | Leave severity undefined — agents produce inconsistent ratings |
+| Define "Out of Scope" to prevent overlap with other agents | Let scope overlap — produces duplicate findings across agents |
+| Use concrete check items with specific patterns to look for | Use vague criteria like "check for issues" or "ensure quality" |
+| Save to `.omp/agents/<agent-name>.md` | Save anywhere else or leave unsaved |
+
+## Pre-Save Checklist
+
+Before saving the agent file, verify:
+
+- [ ] YAML frontmatter has `name`, `description`, and `focus`
+- [ ] Prompt body states the agent's role in the first sentence
+- [ ] At least 3 concrete, actionable check items
+- [ ] Severity guide defines `error`, `warning`, and `info` thresholds
+- [ ] "Out of Scope" section present
+- [ ] `{output_instructions}` is the last line of the prompt body
+- [ ] File saved to `.omp/agents/<agent-name>.md`