superkit-mcp-server 1.0.2 → 1.1.0

package/skills/meta/code-review/SKILL.md

@@ -1,37 +1,44 @@
----
-name: code-review
-description: Systematic multi-perspective code review with consistent quality gates.
-last_updated: 2025-12-20
----
-
-# Code Review Skill
-
-## Overview
-
-A systematic approach to code review that moves beyond "it looks good" to rigorous quality verification. This skill provides specific checklists and procedures for different review types.
-
-## When To Use
-
-- **Self-Review**: Before submitting a PR or finishing `/work`
-- **Peer Review**: When reviewing another agent's or human's code (`/resolve_pr`)
-- **Plan Review**: When validating an implementation plan (`/plan_review`)
-
-## Instrumentation
-
-```bash
-# Log usage when using this skill
-./scripts/log-skill.sh "code-review" "manual" "$$"
-```
-
-## What do you want to do?
-
-1. **Security Review** (Auth, RLS, Input) → `workflows/security-pass.md`
-2. **Performance Review** (Database, Re-renders) → `workflows/performance-pass.md`
-3. **Architecture Review** (State, Data Flow) → `workflows/architecture-pass.md`
-4. **General Quality Check** → `checklists/pre-merge.md`
-
-## Key Principles
-
-- **Review in Passes**: Don't check everything at once. Do a security pass, then a performance pass, etc.
-- **Reference Patterns**: Always check against `docs/solutions/patterns/critical-patterns.md`.
-- **Verify, Don't Guess**: If you see a potential issue, verify it with a quick test or script.
+---
+name: code-review
+description: Systematic multi-perspective code review with consistent quality gates.
+last_updated: 2025-12-20
+---
+
+# Code Review Skill
+
+## Overview
+
+A systematic approach to code review that moves beyond "it looks good" to rigorous quality verification. This skill provides specific checklists and procedures for different review types.
+
+## When To Use
+
+- **Self-Review**: Before submitting a PR or finishing `/work`
+- **Peer Review**: When reviewing another agent's or human's code (`/resolve_pr`)
+- **Plan Review**: When validating an implementation plan (`/plan_review`)
+
+## Instrumentation
+
+```bash
+# Log usage when using this skill
+./scripts/log-skill.sh "code-review" "manual" "$$"
+```
+
+## What do you want to do?
+
+1. **Security Review** (Auth, RLS, Input) → `workflows/security-pass.md`
+2. **Performance Review** (Database, Re-renders) → `workflows/performance-pass.md`
+3. **Architecture Review** (State, Data Flow) → `workflows/architecture-pass.md`
+4. **General Quality Check** → `checklists/pre-merge.md`
+
+## Key Principles
+
+- **Review in Passes**: Don't check everything at once. Do a security pass, then a performance pass, etc.
+- **Reference Patterns**: Always check against `docs/solutions/patterns/critical-patterns.md`.
+- **Verify, Don't Guess**: If you see a potential issue, verify it with a quick test or script.
+
+## Scientific Review Principles
+Adapted from formal peer review standards to improve code review rigor:
+1. **Algorithmic Soundness Check**: Avoid circular logic where state values mask deeper architectural flaws.
+2. **Control Variables Isolation**: Ensure side-effects are heavily isolated and easily testable (simulating scientific controls).
+3. **Absolute Reproducibility**: If a bug or edge-case is discussed in review, verify that the system has enough telemetry/logging to perfectly reproduce it.
+4. **Constructive Tone Constraint**: Frame criticism objectively as an opportunity for improvement. Avoid dismissing implementations without offering actionable, pattern-compliant alternatives.

package/skills/meta/code-review/checklists/pre-merge.md

@@ -1,25 +1,25 @@
-# Pre-Merge Checklist
-
-## Functional Verification
-- [ ] Does the feature meet all implementation plan requirements?
-- [ ] Have all acceptance criteria been verified?
-- [ ] Are there any console errors in the browser?
-- [ ] Is the UI responsive on mobile (simulated)?
-
-## Code Quality
-- [ ] **Linting**: `npm run lint` passes with 0 errors.
-- [ ] **Formatting**: Code formatting is consistent.
-- [ ] **Patterns**: Project patterns are followed (e.g., UI components, file naming).
-- [ ] **Comments**: Complex logic is commented; dead code is removed.
-
-## Testing
-- [ ] **Unit Tests**: Added/updated tests for new logic?
-- [ ] **Pass Rate**: `npm test` passes (or at least no *new* failures).
-
-## Security
-- [ ] **Secrets**: No secrets committed.
-- [ ] **Permissions**: Data access controls verified.
-
-## Documentation
-- [ ] **Changelog**: Entry adds to/is covered by changelog generation.
-- [ ] **Artifacts**: Task and plan updated.
+# Pre-Merge Checklist
+
+## Functional Verification
+- [ ] Does the feature meet all implementation plan requirements?
+- [ ] Have all acceptance criteria been verified?
+- [ ] Are there any console errors in the browser?
+- [ ] Is the UI responsive on mobile (simulated)?
+
+## Code Quality
+- [ ] **Linting**: `npm run lint` passes with 0 errors.
+- [ ] **Formatting**: Code formatting is consistent.
+- [ ] **Patterns**: Project patterns are followed (e.g., UI components, file naming).
+- [ ] **Comments**: Complex logic is commented; dead code is removed.
+
+## Testing
+- [ ] **Unit Tests**: Added/updated tests for new logic?
+- [ ] **Pass Rate**: `npm test` passes (or at least no *new* failures).
+
+## Security
+- [ ] **Secrets**: No secrets committed.
+- [ ] **Permissions**: Data access controls verified.
+
+## Documentation
+- [ ] **Changelog**: Entry adds to/is covered by changelog generation.
+- [ ] **Artifacts**: Task and plan updated.

package/skills/meta/code-review/workflows/architecture-pass.md

@@ -1,26 +1,26 @@
-# Architecture Review Pass
-
-## Checklist
-
-### 1. Component Structure
-- [ ] **Single Responsibility**: Does each component do ONE thing?
-- [ ] **Prop Drilling**: Is context/global state used for deep props?
-- [ ] **Component Size**: Are components <200 lines? Split if larger.
-
-### 2. State Management
-- [ ] **Correct Location**: Is state lifted only as high as needed?
-- [ ] **Server vs Client State**: Is React Query used for server state?
-- [ ] **Form State**: Are forms using controlled components correctly?
-
-### 3. Dependencies
-- [ ] **Circular Imports**: No circular dependencies between modules?
-- [ ] **Layering**: Does data flow UI → Hooks → API → Database?
-- [ ] **External Deps**: Are new packages justified and vetted?
-
-### 4. Patterns
-- [ ] **Project Conventions**: Following existing patterns?
-- [ ] **Canonical Components**: Using project's standard UI components?
-
-## References
-
-- [Critical Patterns](../../../docs/solutions/patterns/critical-patterns.md)
+# Architecture Review Pass
+
+## Checklist
+
+### 1. Component Structure
+- [ ] **Single Responsibility**: Does each component do ONE thing?
+- [ ] **Prop Drilling**: Is context/global state used for deep props?
+- [ ] **Component Size**: Are components <200 lines? Split if larger.
+
+### 2. State Management
+- [ ] **Correct Location**: Is state lifted only as high as needed?
+- [ ] **Server vs Client State**: Is React Query used for server state?
+- [ ] **Form State**: Are forms using controlled components correctly?
+
+### 3. Dependencies
+- [ ] **Circular Imports**: No circular dependencies between modules?
+- [ ] **Layering**: Does data flow UI → Hooks → API → Database?
+- [ ] **External Deps**: Are new packages justified and vetted?
+
+### 4. Patterns
+- [ ] **Project Conventions**: Following existing patterns?
+- [ ] **Canonical Components**: Using project's standard UI components?
+
+## References
+
+- [Critical Patterns](../../../docs/solutions/patterns/critical-patterns.md)

package/skills/meta/code-review/workflows/performance-pass.md

@@ -1,27 +1,27 @@
-# Performance Review Pass
-
-## Checklist
-
-### 1. Rendering Performance
-- [ ] **Unnecessary re-renders**: Are components memoized where needed (`React.memo`, `useMemo`, `useCallback`)?
-- [ ] **Large lists**: Is virtualization used for lists >100 items?
-- [ ] **Heavy computations**: Are expensive calculations deferred or cached?
-
-### 2. Data Fetching
-- [ ] **N+1 Queries**: Are queries batched? No fetching inside loops?
-- [ ] **Caching**: Is React Query used with appropriate stale times?
-- [ ] **Pagination**: Large datasets paginated?
-
-### 3. Bundle Size
-- [ ] **Dynamic imports**: Are heavy modules lazily loaded?
-- [ ] **Tree shaking**: Are unused exports avoided?
-
-## Verification Commands
-
-```bash
-# Look for async calls in loops
-grep -rn "forEach.*await\|map.*await" --include="*.ts" --include="*.tsx" .
-
-# Check bundle size (if build available)
-npm run build && ls -la .next/static/chunks/ | head -20
-```
+# Performance Review Pass
+
+## Checklist
+
+### 1. Rendering Performance
+- [ ] **Unnecessary re-renders**: Are components memoized where needed (`React.memo`, `useMemo`, `useCallback`)?
+- [ ] **Large lists**: Is virtualization used for lists >100 items?
+- [ ] **Heavy computations**: Are expensive calculations deferred or cached?
+
+### 2. Data Fetching
+- [ ] **N+1 Queries**: Are queries batched? No fetching inside loops?
+- [ ] **Caching**: Is React Query used with appropriate stale times?
+- [ ] **Pagination**: Large datasets paginated?
+
+### 3. Bundle Size
+- [ ] **Dynamic imports**: Are heavy modules lazily loaded?
+- [ ] **Tree shaking**: Are unused exports avoided?
+
+## Verification Commands
+
+```bash
+# Look for async calls in loops
+grep -rn "forEach.*await\|map.*await" --include="*.ts" --include="*.tsx" .
+
+# Check bundle size (if build available)
+npm run build && ls -la .next/static/chunks/ | head -20
+```

package/skills/meta/code-review/workflows/security-pass.md

@@ -1,29 +1,29 @@
-# Security Review Pass
-
-## Checklist
-
-### 1. Authentication & Authorization
-- [ ] **Auth Guards**: Are protected pages wrapped in `AuthGuard` or middleware check?
-- [ ] **RLS Policies**: Do Supabase queries rely on RLS (Row Level Security)?
-  - *Check*: Are we using `supabase-js` client (enforces RLS) or `service_role` (bypasses RLS)?
-  - *Rule*: ONLY use `service_role` in backend API routes or Edge Functions, NEVER in frontend.
-- [ ] **User Ownership**: Do write operations verify `user_id` matches the authenticated user?
-
-### 2. Data Validation
-- [ ] **Input Sanitization**: Are inputs validated (Zod/Yup)?
-- [ ] **Type Safety**: Are we using strict TypeScript types? avoiding `any`?
-- [ ] **SQL Injection**: Are we using parameterized queries (Supabase does this by default)?
-
-### 3. Secrets Management
-- [ ] **Environment Variables**: Are secrets (API keys) prefixed with `NEXT_PUBLIC_` ONLY if they are safe for public exposure?
-- [ ] **Hardcoding**: `grep` for hardcoded keys or tokens.
-
-## Verification Commands
-
-```bash
-# Find service role usage (potential bypass)
-grep -r "createClient" . | grep "service_role"
-
-# Find dangerous public keys
-grep -r "NEXT_PUBLIC" . | grep "SECRET"
-```
+# Security Review Pass
+
+## Checklist
+
+### 1. Authentication & Authorization
+- [ ] **Auth Guards**: Are protected pages wrapped in `AuthGuard` or middleware check?
+- [ ] **RLS Policies**: Do Supabase queries rely on RLS (Row Level Security)?
+  - *Check*: Are we using `supabase-js` client (enforces RLS) or `service_role` (bypasses RLS)?
+  - *Rule*: ONLY use `service_role` in backend API routes or Edge Functions, NEVER in frontend.
+- [ ] **User Ownership**: Do write operations verify `user_id` matches the authenticated user?
+
+### 2. Data Validation
+- [ ] **Input Sanitization**: Are inputs validated (Zod/Yup)?
+- [ ] **Type Safety**: Are we using strict TypeScript types? avoiding `any`?
+- [ ] **SQL Injection**: Are we using parameterized queries (Supabase does this by default)?
+
+### 3. Secrets Management
+- [ ] **Environment Variables**: Are secrets (API keys) prefixed with `NEXT_PUBLIC_` ONLY if they are safe for public exposure?
+- [ ] **Hardcoding**: `grep` for hardcoded keys or tokens.
+
+## Verification Commands
+
+```bash
+# Find service role usage (potential bypass)
+grep -r "createClient" . | grep "service_role"
+
+# Find dangerous public keys
+grep -r "NEXT_PUBLIC" . | grep "SECRET"
+```

package/skills/meta/compound-docs/SKILL.md

@@ -1,133 +1,133 @@
----
-name: compound-docs
-description: Document solved problems for knowledge persistence
----
-
-# Compound Documentation Skill
-
-Manages solution documentation in `docs/solutions/` for knowledge persistence across sessions.
-
-## Overview
-
-When you solve a problem, document it so the solution can be found and reused later.
-
-## What do you want to do?
-
-1. **Document a solution** → Use `/compound` workflow
-2. **Find existing solutions** → See "Searching Solutions" below
-3. **Promote to pattern** → See "Pattern Promotion" below
-4. **Validate schema** → See "YAML Validation" below
-
----
-
-## Instrumentation
-
-```bash
-# Log usage when using this skill
-./scripts/log-skill.sh "compound-docs" "manual" "$$"
-```
-
-## Searching Solutions
-
-```bash
-# Search by keyword
-grep -r "keyword" docs/solutions/
-
-# Search by tag
-grep -l "tags:.*performance" docs/solutions/**/*.md
-
-# Search by problem type
-ls docs/solutions/performance-issues/
-```
-
-## Pattern Promotion
-
-When an issue occurs 3+ times:
-
-1. Search for similar solutions:
-   ```bash
-   grep -r "similar terms" docs/solutions/
-   ```
-
-2. Add to critical patterns:
-   ```bash
-   # Edit docs/solutions/patterns/critical-patterns.md
-   ```
-
-3. Format:
-   ```markdown
-   ### Pattern #{N}: {Name}
-   
-   **Problem:** {What goes wrong}
-   
-   **❌ WRONG:**
-   ```code
-   {incorrect}
-   ```
-   
-   **✅ CORRECT:**
-   ```code
-   {correct}
-   ```
-   ```
-
-## YAML Validation
-
-All solutions must have valid frontmatter:
-
-```yaml
----
-date: "YYYY-MM-DD"
-problem_type: "{from schema.yaml}"
-severity: "critical|high|medium|low"
-symptoms:
-  - "symptom 1"
-root_cause: "{from schema.yaml}"
-tags:
-  - tag1
----
-```
-
-See `docs/solutions/schema.yaml` for valid enum values.
-
-## Documenting Failures & Learnings
-
-When documenting solutions, capture the full journey:
-
-### What to Include
-- ✅ Failed attempts with explanations
-- ✅ Incorrect assumptions and corrections
-- ✅ Key insights from mistakes
-- ✅ Course corrections and why
-- ✅ Time investment (helps prioritize future similar issues)
-
-### Example Pattern
-```markdown
-## Investigation Steps
-
-| Attempt | Hypothesis | Result |
-|---------|------------|--------|
-| 1. Check API logs | API might be timing out | ❌ No timeouts found |
-| 2. Review database queries | N+1 query suspected | ❌ Queries were optimized |
-| 3. Check cache invalidation | Cache might be stale | ✅ Found cache not clearing |
-
-## Lessons Learned
-
-### Mistakes Made
-- **Assumption:** Assumed the API was the bottleneck
-  - **Why wrong:** Didn't check cache layer first
-  - **Correction:** Should always check cache before API
-
-### Key Breakthrough
-- **Insight:** Realized cache invalidation logic was only running on UPDATE, not DELETE
-  - **Impact:** Led directly to the solution
-```
-
-> [!TIP]
-> **Document the journey, not just the destination.** Future readers learn from understanding WHY failed approaches didn't work.
-
-## References
-
-- Schema: `docs/solutions/schema.yaml`
-- Template: `docs/solutions/templates/solution-template.md`
-- Patterns: `docs/solutions/patterns/critical-patterns.md`
+---
+name: compound-docs
+description: Document solved problems for knowledge persistence
+---
+
+# Compound Documentation Skill
+
+Manages solution documentation in `docs/solutions/` for knowledge persistence across sessions.
+
+## Overview
+
+When you solve a problem, document it so the solution can be found and reused later.
+
+## What do you want to do?
+
+1. **Document a solution** → Use `/compound` workflow
+2. **Find existing solutions** → See "Searching Solutions" below
+3. **Promote to pattern** → See "Pattern Promotion" below
+4. **Validate schema** → See "YAML Validation" below
+
+---
+
+## Instrumentation
+
+```bash
+# Log usage when using this skill
+./scripts/log-skill.sh "compound-docs" "manual" "$$"
+```
+
+## Searching Solutions
+
+```bash
+# Search by keyword
+grep -r "keyword" docs/solutions/
+
+# Search by tag
+grep -l "tags:.*performance" docs/solutions/**/*.md
+
+# Search by problem type
+ls docs/solutions/performance-issues/
+```
+
+## Pattern Promotion
+
+When an issue occurs 3+ times:
+
+1. Search for similar solutions:
+   ```bash
+   grep -r "similar terms" docs/solutions/
+   ```
+
+2. Add to critical patterns:
+   ```bash
+   # Edit docs/solutions/patterns/critical-patterns.md
+   ```
+
+3. Format:
+   ```markdown
+   ### Pattern #{N}: {Name}
+   
+   **Problem:** {What goes wrong}
+   
+   **❌ WRONG:**
+   ```code
+   {incorrect}
+   ```
+   
+   **✅ CORRECT:**
+   ```code
+   {correct}
+   ```
+   ```
+
+## YAML Validation
+
+All solutions must have valid frontmatter:
+
+```yaml
+---
+date: "YYYY-MM-DD"
+problem_type: "{from schema.yaml}"
+severity: "critical|high|medium|low"
+symptoms:
+  - "symptom 1"
+root_cause: "{from schema.yaml}"
+tags:
+  - tag1
+---
+```
+
+See `docs/solutions/schema.yaml` for valid enum values.
+
+## Documenting Failures & Learnings
+
+When documenting solutions, capture the full journey:
+
+### What to Include
+- ✅ Failed attempts with explanations
+- ✅ Incorrect assumptions and corrections
+- ✅ Key insights from mistakes
+- ✅ Course corrections and why
+- ✅ Time investment (helps prioritize future similar issues)
+
+### Example Pattern
+```markdown
+## Investigation Steps
+
+| Attempt | Hypothesis | Result |
+|---------|------------|--------|
+| 1. Check API logs | API might be timing out | ❌ No timeouts found |
+| 2. Review database queries | N+1 query suspected | ❌ Queries were optimized |
+| 3. Check cache invalidation | Cache might be stale | ✅ Found cache not clearing |
+
+## Lessons Learned
+
+### Mistakes Made
+- **Assumption:** Assumed the API was the bottleneck
+  - **Why wrong:** Didn't check cache layer first
+  - **Correction:** Should always check cache before API
+
+### Key Breakthrough
+- **Insight:** Realized cache invalidation logic was only running on UPDATE, not DELETE
+  - **Impact:** Led directly to the solution
+```
+
+> [!TIP]
+> **Document the journey, not just the destination.** Future readers learn from understanding WHY failed approaches didn't work.
+
+## References
+
+- Schema: `docs/solutions/schema.yaml`
+- Template: `docs/solutions/templates/solution-template.md`
+- Patterns: `docs/solutions/patterns/critical-patterns.md`

package/skills/meta/debug/SKILL.md

@@ -1,40 +1,40 @@
----
-name: debug
-description: Systematic debugging with structured reproduction and root cause analysis.
-last_updated: 2025-12-20
----
-
-# Debug Skill
-
-## Overview
-
-Don't guess; verify. This skill guides you through the systematic process of identifying, reproducing, and fixing bugs.
-
-## When To Use
-
-- **Users report a bug**
-- **You encounter an unexpected error**
-- **Tests are failing inexplicably**
-
-## Instrumentation
-
-```bash
-# Log usage when using this skill
-./scripts/log-skill.sh "debug" "manual" "$$"
-```
-
-## What do you want to do?
-
-1. **Reproduce an issue** → `workflows/reproduce-issue.md`
-2. **Find Root Cause** → `workflows/root-cause-analysis.md`
-3. **Create Bug Report** → `templates/bug-report.template.md`
-4. **Research Error Messages** → `references/common-errors.md`
-
-## The Golden Rule of Debugging
-
-> **"If you haven't reproduced it, you haven't fixed it."**
-
-Always implement a reproduction case (test or script) BEFORE attempting a fix. Highly recommended to use the template at `docs/templates/repro-script-template.sh` and store artifacts in `scripts/repro/`.
-
-> [!NOTE]
-> No top-level `debug/` folder exists. Use `skills/debug/` for guidance and `scripts/repro/` for artifacts.
+---
+name: debug
+description: Systematic debugging with structured reproduction and root cause analysis.
+last_updated: 2025-12-20
+---
+
+# Debug Skill
+
+## Overview
+
+Don't guess; verify. This skill guides you through the systematic process of identifying, reproducing, and fixing bugs.
+
+## When To Use
+
+- **Users report a bug**
+- **You encounter an unexpected error**
+- **Tests are failing inexplicably**
+
+## Instrumentation
+
+```bash
+# Log usage when using this skill
+./scripts/log-skill.sh "debug" "manual" "$$"
+```
+
+## What do you want to do?
+
+1. **Reproduce an issue** → `workflows/reproduce-issue.md`
+2. **Find Root Cause** → `workflows/root-cause-analysis.md`
+3. **Create Bug Report** → `templates/bug-report.template.md`
+4. **Research Error Messages** → `references/common-errors.md`
+
+## The Golden Rule of Debugging
+
+> **"If you haven't reproduced it, you haven't fixed it."**
+
+Always implement a reproduction case (test or script) BEFORE attempting a fix. Highly recommended to use the template at `docs/templates/repro-script-template.sh` and store artifacts in `scripts/repro/`.
+
+> [!NOTE]
+> No top-level `debug/` folder exists. Use `skills/debug/` for guidance and `scripts/repro/` for artifacts.