sequant 1.0.0

package/templates/skills/qa/references/code-review-checklist.md

@@ -0,0 +1,77 @@
+# Code Review Checklist
+
+## Duplicate Utility Check
+
+Before approving any new helper functions, components, or types, check:
+1. `docs/patterns/HELPERS.md` - Does a similar helper already exist?
+2. `docs/patterns/COMPONENTS.md` - Does a similar component already exist?
+3. `docs/patterns/TYPES.md` - Does a similar type already exist?
+
+If duplicates are found, flag as `AC_MET_BUT_NOT_A_PLUS` with recommendation to use existing utilities.
+
+## Integration Verification
+
+Before approving, verify the implementation integrates properly:
+
+### 1. File Locations
+Are new files in correct directories per `scripts/README.md` structure?
+```bash
+git diff main...HEAD --name-only | grep "^scripts/"
+```
+
+### 2. Pattern Compliance
+Do new scripts follow existing patterns?
+- Scripts: Inline Supabase client, env validation, CLI flags (`--dry-run`, `--limit`)
+- Components: Follow established admin patterns (List + Card + Modal)
+- Compare with similar files: `ls scripts/fix/` or `ls components/admin/`
+
+### 3. Documentation References
+Check for dangling refs in CLAUDE.md:
+```bash
+grep -oE 'docs/[A-Z_]+\.md' CLAUDE.md | sort -u | while read f; do
+  [ ! -f "$f" ] && echo "Missing: $f"
+done
+```
+
+### 4. CLAUDE.md Updates Needed?
+If adding new scripts/commands, should they be documented?
+- New scripts in `scripts/` → Add to Common Commands section
+- New patterns → Add to Key Patterns or patterns catalog
+
+## Do NOT Nitpick
+
+Skip trivial formatting if the repo already has automated formatting tools.
+
+## RLS-Protected Table Access Check
+
+Admin pages must use `supabaseAdmin`:
+
+```bash
+rls_tables="content_updates|content_ideas|fact_check_logs"
+admin_files=$(git diff main...HEAD --name-only | grep -E "^app/admin/")
+if [[ -n "$admin_files" ]]; then
+  for file in $admin_files; do
+    if [[ -f "$file" ]]; then
+      if grep -q "from '@/lib/supabase'" "$file" && grep -qE "\.from\(['\"]($rls_tables)['\"]" "$file"; then
+        echo "❌ BLOCKER: $file uses anon client for RLS-protected table"
+      fi
+    fi
+  done
+fi
+```
+
+## Integration Check
+
+Verify new exports are imported somewhere:
+```bash
+new_files=$(git diff main...HEAD --name-only --diff-filter=A | grep -E "\.(ts|tsx)$" || true)
+for file in $new_files; do
+  exports=$(grep -oE "export (const|function|class|type|interface) ([A-Za-z_][A-Za-z0-9_]*)" "$file" | awk '{print $3}')
+  for exp in $exports; do
+    import_count=$(grep -r "import.*$exp" --include="*.ts" --include="*.tsx" . | grep -v "$file" | wc -l | xargs)
+    if [[ $import_count -eq 0 ]]; then
+      echo "⚠️ '$exp' exported from $file but never imported"
+    fi
+  done
+done
+```

package/templates/skills/qa/references/quality-gates.md

@@ -0,0 +1,95 @@
+# Quality Gates & Verdict Criteria
+
+## Automated Check Synthesis
+
+Combine agent outputs into a unified quality assessment:
+
+| Agent | Output | Weight |
+|-------|--------|--------|
+| Type Safety Checker | Type issues count, verdict | High - blocking if issues > 3 |
+| Scope/Size Checker | Files changed, LOC, assessment | Medium - warning if very large |
+| Security Scanner | Critical/warning/info counts | High - blocking if criticals > 0 |
+| RLS Checker (conditional) | Violations found | High - blocking if violations |
+
+**Synthesis Rules:**
+- **Any FAIL verdict** → Flag as blocker in manual review
+- **Security criticals** → Block merge, require fix before proceeding
+- **All PASS** → Proceed with confidence to manual review
+- **WARN verdicts** → Note in review, verify manually
+
+## Verdict Criteria
+
+### `READY_FOR_MERGE`
+
+Must meet ALL of:
+- ✅ All AC items marked `MET`
+- ✅ Type issues = 0 (no `any` additions)
+- ✅ Deleted tests = 0 (or justified)
+- ✅ Purpose Test: All files necessary
+- ✅ Proportionality Test: Size matches AC complexity
+- ✅ Risk Test: Blast radius understood and acceptable
+- ✅ Reversibility Test: Clean revert possible
+- ✅ **Adversarial Test: Failure path tested**
+- ✅ **Edge Case Test: At least 1 edge case per AC tested**
+
+### `AC_MET_BUT_NOT_A_PLUS`
+
+AC met, but one or more issues:
+- ⚠️ Minor scope creep (1-2 extra files)
+- ⚠️ Over-engineering (abstraction not required)
+- ⚠️ Size larger than expected but justified
+- ⚠️ Type issues present but necessary
+- ⚠️ Code works but could be cleaner
+
+**Action:** List specific improvements, but don't block merge if working
+
+### `AC_NOT_MET`
+
+Any of:
+- ❌ One or more AC items `NOT_MET` or `PARTIALLY_MET`
+- ❌ Deleted tests without justification
+- ❌ Major scope creep (many unrelated files)
+- ❌ Type safety violations (adding `any` without reason)
+- ❌ Schema changes without migrations
+- ❌ Breaking changes to shared code
+
+**Action:** Block merge, list required fixes
+
+## Code Review Decision Framework
+
+### 1. Purpose Test
+**Question:** Can I explain why each changed file was necessary for the AC?
+- ✅ **Yes, all files:** Strong signal for `READY_FOR_MERGE`
+- ⚠️ **Yes, most files:** May indicate minor scope creep → `AC_MET_BUT_NOT_A_PLUS`
+- ❌ **No, many files unclear:** Scope creep → `AC_NOT_MET`
+
+### 2. Proportionality Test
+**Question:** Is the diff size reasonable for AC complexity?
+
+**Reference:**
+- 1-3 simple AC: <100 LOC expected
+- 4-6 medium AC: 100-300 LOC expected
+- 7+ complex AC: 300-500 LOC expected
+
+### 3. Risk Test
+**Question:** What's the blast radius if this breaks?
+- ✅ **Isolated feature, easy to revert:** Lower bar for approval
+- ⚠️ **Touches shared utilities:** Scrutinize more carefully
+- ❌ **Changes core types, schemas, or auth:** Highest bar
+
+### 4. Reversibility Test
+**Question:** Would reverting lose anything besides the AC?
+- ✅ **No, only AC work:** Clean implementation
+- ⚠️ **Yes, minor refactors:** Document them, may still approve
+- ❌ **Yes, major refactors/features:** Scope creep
+
+## Check Interpretation
+
+- **Type issues** = 0: ✅ Good
+- **Type issues** > 0: ⚠️ Review each case, ensure justified
+- **Deleted tests** > 0: ❌ Blocker unless tests obsolete
+- **Files changed**: Compare to similar features for proportionality
+- **Net LOC**: Should align with AC complexity (see Size Check guidelines)
+- **Unintegrated exports**: ⚠️ Warning only
+- **Security criticals** > 0: ❌ Blocker
+- **Security warnings** > 0: ⚠️ Review each case

package/templates/skills/qa/references/testing-requirements.md

@@ -0,0 +1,109 @@
+# Testing Requirements
+
+## Adversarial Thinking Checklist
+
+**STOP and ask these questions before any READY_FOR_MERGE verdict:**
+
+### 1. "What would break this?"
+- [ ] Identified at least 2 failure scenarios
+- [ ] Actually tested each failure scenario (not just thought about it)
+- [ ] Documented what happens when failure occurs
+
+### 2. "What assumptions am I making?"
+- [ ] Listed key assumptions (API behavior, data format, status codes)
+- [ ] Validated each assumption with actual test
+- [ ] If assumption can't be tested, flagged as risk
+
+### 3. "What's the unhappy path?"
+- [ ] Tested behavior when inputs are invalid
+- [ ] Tested behavior when dependencies fail
+- [ ] Tested behavior when resources don't exist
+
+### 4. "Did I test the feature's PRIMARY PURPOSE?"
+- [ ] If feature handles errors → actually triggered an error
+- [ ] If feature retries → actually triggered a retry
+- [ ] If feature validates → actually provided invalid input
+- [ ] If feature blocks → actually tried the blocked action
+
+## Failure Path Testing by Feature Type
+
+| Feature Type | Must Test |
+|--------------|-----------|
+| Retry mechanism | Force a failure, verify retry triggers |
+| Validation | Submit invalid data, verify rejection |
+| Error handling | Cause an error, verify graceful handling |
+| Auth/permissions | Try unauthorized action, verify blocked |
+| Rate limiting | Exceed limit, verify throttled |
+
+## Red Flags (Incomplete Testing)
+
+- ❌ "All tests pass" but no failure scenarios tested
+- ❌ "Feature works" but only success path verified
+- ❌ Unit tests pass but integration never tested
+- ❌ No manual testing of edge cases
+
+## Edge Case Verification
+
+For each AC, identify and test at least ONE edge case:
+
+| AC | Happy Path Tested | Edge Case Identified | Edge Case Tested |
+|----|-------------------|---------------------|------------------|
+| AC-1 | ✅ | Empty input | ✅ |
+| AC-2 | ✅ | Concurrent access | ❌ (flagged as risk) |
+| AC-3 | ✅ | Non-existent resource | ✅ |
+
+**Common edge cases to consider:**
+- Empty/null inputs
+- Maximum/minimum values
+- Concurrent operations
+- Non-existent resources
+- Permission denied scenarios
+- Network/timeout failures
+- Invalid state transitions
+
+## Admin Feature Smoke Test
+
+**REQUIRED for `app/admin/` changes:**
+
+```bash
+admin_modified=$(git diff main...HEAD --name-only | grep -E "^app/admin/" | head -1)
+if [[ -n "$admin_modified" ]]; then
+  echo "⚠️ Admin files modified - smoke test required"
+fi
+```
+
+**Smoke test checklist:**
+- [ ] Navigate to `/admin/news` - stat cards show data
+- [ ] Navigate to affected feature page - content displays
+- [ ] If feature queries `content_updates`, `content_ideas`, `fact_check_logs` - verify data appears
+
+**Smoke test failure = BLOCKER**
+
+## Cache & RLS Verification
+
+**If feature displays content on public pages:**
+- [ ] Verify `revalidatePath('/')` called if content appears on homepage
+- [ ] Verify `revalidatePath` covers all pages displaying the content
+- [ ] Test in incognito (anon client) to verify public reads work
+
+**Check RLS allows public reads:**
+```sql
+SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = 'TABLE_NAME';
+```
+
+## Integration Smoke Test
+
+**For external system integrations:**
+
+1. **Identify the integration point** - Document: `Integration: <system name>`
+
+2. **Validate assumptions**
+   - [ ] API contract verified against official docs
+   - [ ] Data format assumptions tested
+   - [ ] Authentication method confirmed
+   - [ ] Error response handling matches actual API
+
+3. **Manual smoke test**
+   - [ ] Actually invoke the integration once
+   - [ ] Verify data flows end-to-end
+   - [ ] Document: "Tested by: <description>"

package/templates/skills/qa/scripts/quality-checks.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# Quality checks script for /qa command
+# Run these checks before detailed review
+
+set -e
+
+echo "🔍 Running automated quality checks..."
+echo ""
+
+# 1. Type safety check - detect 'any' type usage
+type_issues=$(git diff main...HEAD | grep -E ":\s*any[,)]|as any" | wc -l | xargs)
+if [[ $type_issues -gt 0 ]]; then
+  echo "⚠️  WARNING: $type_issues potential 'any' type usages"
+else
+  echo "✅ Type safety: No 'any' type additions"
+fi
+
+# 2. Deleted tests check
+deleted_tests=$(git diff main...HEAD --diff-filter=D --name-only | grep -E "\\.test\\.|\\spec\\." | wc -l | xargs)
+if [[ $deleted_tests -gt 0 ]]; then
+  echo "❌ BLOCKER: $deleted_tests test files deleted"
+else
+  echo "✅ Test coverage: No test files deleted"
+fi
+
+# 3. Scope check - files changed
+files_changed=$(git diff main...HEAD --name-only | wc -l | xargs)
+echo "📊 Files changed: $files_changed"
+
+# 4. Size check - LOC added/removed
+additions=$(git diff main...HEAD --numstat | awk '{sum+=$1} END {print sum+0}')
+deletions=$(git diff main...HEAD --numstat | awk '{sum+=$2} END {print sum+0}')
+net_change=$((additions - deletions))
+echo "📊 Diff size: +$additions -$deletions (net: $net_change lines)"
+
+# 5. AC proportionality assessment
+echo ""
+if [[ $net_change -lt 100 ]]; then
+  echo "✅ Size: Small change (<100 net LOC)"
+elif [[ $net_change -lt 300 ]]; then
+  echo "✅ Size: Medium change (100-300 net LOC)"
+elif [[ $net_change -lt 500 ]]; then
+  echo "⚠️  Size: Large change (300-500 net LOC) - verify proportional to AC"
+else
+  echo "❌ Size: Very large (>500 net LOC) - may indicate scope creep"
+fi
+
+# 6. RLS-protected table access check (admin pages must use supabaseAdmin)
+echo ""
+echo "🔒 Checking RLS-protected table access..."
+rls_tables="content_updates|content_ideas|fact_check_logs"
+admin_files=$(git diff main...HEAD --name-only | grep -E "^app/admin/" || true)
+if [[ -n "$admin_files" ]]; then
+  rls_violations=0
+  for file in $admin_files; do
+    if [[ -f "$file" ]]; then
+      # Check if file imports anon client and queries RLS-protected tables
+      if grep -q "from '@/lib/supabase'" "$file" && grep -qE "\.from\(['\"]($rls_tables)['\"]" "$file"; then
+        echo "❌ BLOCKER: $file uses anon client for RLS-protected table"
+        echo "   Fix: Use supabaseAdmin from '@/lib/supabase-admin' instead"
+        rls_violations=$((rls_violations + 1))
+      fi
+    fi
+  done
+  if [[ $rls_violations -eq 0 ]]; then
+    echo "✅ RLS access: No violations found in admin files"
+  fi
+else
+  echo "   No admin files modified"
+fi
+
+# 7. Integration check - verify new exports are imported somewhere
+echo ""
+echo "🔌 Checking integration of new exports..."
+new_files=$(git diff main...HEAD --name-only --diff-filter=A | grep -E "\.(ts|tsx)$" || true)
+if [[ -n "$new_files" ]]; then
+  unintegrated=0
+  for file in $new_files; do
+    if [[ -f "$file" ]]; then
+      exports=$(grep -oE "export (const|function|class|type|interface) ([A-Za-z_][A-Za-z0-9_]*)" "$file" 2>/dev/null | awk '{print $3}' || true)
+      for exp in $exports; do
+        if [[ -n "$exp" ]]; then
+          import_count=$(grep -r "import.*$exp" --include="*.ts" --include="*.tsx" . 2>/dev/null | grep -v "$file" | wc -l | xargs)
+          if [[ $import_count -eq 0 ]]; then
+            echo "⚠️  WARNING: '$exp' exported from $file but never imported"
+            unintegrated=$((unintegrated + 1))
+          fi
+        fi
+      done
+    fi
+  done
+  if [[ $unintegrated -eq 0 ]]; then
+    echo "✅ Integration: All exports are imported"
+  fi
+else
+  echo "   No new TypeScript files added"
+fi
+
+# 8. Security scan - OWASP vulnerability checks
+echo ""
+echo "🔒 Running security scan..."
+if command -v npx &> /dev/null; then
+  npx tsx scripts/lib/__tests__/run-security-scan.ts 2>/dev/null || echo "   Security scanner not available, skipping..."
+else
+  echo "   npx not available, skipping security scan"
+fi
+
+echo ""
+echo "✅ Quality checks complete"

package/templates/skills/reflect/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: reflect
+description: "Strategic reflection on workflow effectiveness and continuous improvement"
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - mcp__supabase__execute_sql
+---
+
+# Reflection Agent
+
+You are the "Reflection Agent" for the current repository.
+
+## Purpose
+
+When invoked as `/reflect`, your job is to:
+
+1. Analyze the recent work session for workflow effectiveness
+2. Identify friction points, inefficiencies, or missing context
+3. Propose targeted improvements to commands, docs, or processes
+4. Balance documentation completeness with actionability (avoid bloat)
+
+## Behavior
+
+When called without arguments:
+- Reflect on the current conversation/session
+- Analyze what worked well and what could be improved
+- Auto-detect current workflow phase (planning, implementation, QA)
+
+When called with a focus area:
+- `/reflect commands` - Focus on slash command effectiveness
+- `/reflect docs` - Focus on documentation (CLAUDE.md, other docs/)
+- `/reflect workflow` - Focus on development workflow (includes historical data)
+- `/reflect tools` - Focus on tool usage patterns
+- `/reflect planning` - Focus on planning phase (use during/after `/spec`)
+- `/reflect implementation` - Focus on implementation phase (use during/after `/exec`)
+- `/reflect qa` - Focus on QA/review phase (use during/after `/qa`)
+
+## Reflection Framework
+
+### 1. Session Analysis
+
+**Effectiveness Metrics:**
+- How many attempts to complete tasks?
+- Were there repeated searches for the same information?
+- Did I have the right context at the right time?
+- Were there ambiguities that blocked progress?
+
+**Friction Points:**
+- What information was hard to find?
+- What decisions took multiple iterations?
+- What patterns did I have to discover vs. having documented?
+- Where did I waste time or tokens?
+
+### 2. Root Cause Analysis
+
+For each friction point, determine:
+- **Missing documentation:** Information exists but isn't documented
+- **Documentation bloat:** Information documented but hard to find/use
+- **Process gap:** No established pattern for this scenario
+- **Tool limitation:** Current tools don't support this workflow
+- **Command gap:** Common task lacks dedicated slash command
+
+### 3. Improvement Proposals
+
+See [documentation-tiers.md](references/documentation-tiers.md) for the 4-tier system.
+
+**For Documentation Changes:**
+- **What to add:** Missing patterns, decisions, or context
+- **What to remove:** Outdated, redundant, or rarely-used content
+- **What to restructure:** Information that's hard to find or too verbose
+- **Where to put it:** Right file, right section, right level of detail
+
+## Documentation Balance Principles
+
+**Avoid these anti-patterns:**
+❌ **Over-documentation:** Every edge case documented exhaustively
+❌ **Stale documentation:** Old information that's no longer accurate
+❌ **Premature documentation:** Documenting patterns before they're stable
+❌ **Redundant documentation:** Same info in multiple places
+❌ **Example overload:** Too many examples that obscure the pattern
+
+**Follow these principles:**
+✅ **Just-in-time documentation:** Document when pattern stabilizes (2-3 uses)
+✅ **Progressive disclosure:** Brief overview → link to details
+✅ **Living documentation:** Review and prune quarterly
+✅ **Decision logs:** Document *why* not just *what*
+✅ **Searchable patterns:** Use consistent keywords for grep/search
+
+## Output Structure
+
+### **Session Summary**
+- What was accomplished
+- What went smoothly
+- What caused friction
+
+### **Effectiveness Analysis**
+- Token usage efficiency (did we re-read files unnecessarily?)
+- Context gathering (did we find info quickly?)
+- Decision making (were choices clear or iterative?)
+- Pattern reuse (did we reinvent vs. follow existing patterns?)
+
+### **Proposed Changes**
+
+For each proposal, specify:
+1. **Change Type:** [Add | Update | Remove | Restructure]
+2. **Target:** [File path or command name]
+3. **Rationale:** [Why this change improves workflow]
+4. **Content:** [Specific text to add/change, or "see draft"]
+5. **Priority:** [High | Medium | Low]
+6. **Risk:** [What could go wrong with this change]
+
+### **Documentation Health Check**
+
+Review CLAUDE.md size and relevance:
+- Current line count (target: 700-800)
+- Sections that feel bloated
+- Sections that are missing
+- Redundancy check
+- Extract candidates (sections >50 lines)
+- Recommendation: [Prune | Expand | Restructure | Extract | Good as-is]
+
+### **Action Items**
+
+Generate a checklist:
+- [ ] Add section to CLAUDE.md: [topic]
+- [ ] Update slash command: [command name]
+- [ ] Move to docs/archive/: [file name]
+- [ ] Create new command: [command name]
+- [ ] Remove outdated content: [location]
+
+## Workflow Analytics
+
+For `/reflect workflow`, use the SQL queries in [workflow-queries.ts](scripts/workflow-queries.ts) to analyze historical data.
+
+See [phase-reflection.md](references/phase-reflection.md) for phase-specific guidance.
+
+## Reflection Cadence
+
+**Suggested usage:**
+- After completing a major feature
+- When workflow feels inefficient
+- Monthly for general health check
+- After onboarding new team members (capture confusion points)
+
+## Meta-Reflection
+
+At the end of reflection, ask:
+- Is this reflection session providing value?
+- Are the proposed changes specific enough to act on?
+- Did I identify root causes or just symptoms?
+- Will these changes be maintainable long-term?
+- Am I in the right workflow phase for this reflection focus?

package/templates/skills/reflect/references/documentation-tiers.md

@@ -0,0 +1,70 @@
+# Documentation Tiers
+
+Organize information by access frequency:
+
+## Tier 1: Hot Path (CLAUDE.md)
+
+- Used in 50%+ of sessions
+- Core architecture decisions
+- Most common commands and patterns
+- **Target: 700-800 lines** (check with `wc -l CLAUDE.md`)
+- Quick summaries with links to detailed docs
+- Review monthly
+
+**Keep in CLAUDE.md:**
+- ✅ Core architecture patterns (database, routing, components)
+- ✅ Most common commands (development, discovery, enrichment)
+- ✅ Critical patterns (validation, audit logging, state management)
+- ✅ Quick reference information needed in 50%+ of sessions
+
+## Tier 2: Reference (docs/ folder)
+
+- Used in 10-50% of sessions
+- Detailed specs, schemas, guides
+- Can be 1000+ lines per doc
+- Review quarterly
+
+**Current specialized docs:**
+- `CITY_COVERAGE.md` - Coverage analysis workflow
+- `SHOP_DISCOVERY.md` - Discovery & enrichment pipeline
+- `TESTING.md` - UI testing patterns
+- `ADMIN_CMS_ARCHITECTURE.md` - Full CMS architecture
+
+## Tier 3: Archive (docs/archive/)
+
+- Used in <10% of sessions
+- Historical context, deprecated patterns
+- Move here after 6 months of non-use
+- Keep for searchability, not active use
+
+## Tier 4: Code Comments
+
+- Implementation-specific details
+- Edge case handling
+- Why certain approaches were chosen
+- Lives with the code, not in docs
+
+## When to Extract to Separate Docs
+
+Move from CLAUDE.md to docs/ when:
+- ✅ Section exceeds 50 lines
+- ✅ Contains detailed workflow steps (>3 steps)
+- ✅ Has extensive examples or command variations
+- ✅ Used occasionally but not in every session
+- ✅ Could evolve independently
+
+## Documentation Health Metrics
+
+**CLAUDE.md Health Check:**
+- Current line count vs target (700-800)
+- Lines added in last month
+- Sections that feel bloated
+- Sections that are missing
+- Redundancy between CLAUDE.md and docs/
+
+**Recommendations:**
+- **Prune:** >900 lines, multiple bloated sections
+- **Expand:** <600 lines, missing critical patterns
+- **Restructure:** Hard to find information
+- **Extract:** Multiple sections >50 lines
+- **Good as-is:** 700-800 lines, balanced content