co8/secret-sauce

Secret Sauce v2

Production-tested coding standards, patterns, and automated quality gates for TypeScript, Next.js, React, and Supabase projects.

14 reference guides covering every layer of the stack, 5 framework-specific rule sets that enforce best practices, 6 ready-to-use project templates, and a parallel review team of specialized subagents that catch bugs, security issues, silent failures, and design flaws before they ship.

Why Secret Sauce?

• Instant project setup — CLAUDE.md template, settings, and planning docs get you productive in seconds
• Automated quality gates — 3-agent quick review or 5-agent full review, all dispatched in parallel
• Real patterns, not theory — Every rule and reference extracted from production codebases
• AI flow patterns — OpenAI SDK v6 + Anthropic SDK with Zod validation, streaming, tool use
• Full-stack coverage — TypeScript, Next.js, React, Supabase, Tailwind v4, Vitest, security, deployment

---

Quick Reference

| Category | Reference File | Auto-Review Agent | |----------|----------------|-------------------| | Tech Stack | references/tech-stack.md | — | | Project Setup | references/claude-md-template.md | — | | Project Tracking | references/project-tracking.md | — | | Coding Standards | references/coding-standards.md | feature-dev:code-reviewer | | Centralization | references/centralization-patterns.md | pr-review-toolkit:code-simplifier | | Tailwind v4 | references/tailwind-v4.md | — | | AI Development | references/ai-flow-patterns.md | pr-review-toolkit:silent-failure-hunter | | Data Fetching | references/data-fetching.md | pr-review-toolkit:silent-failure-hunter | | Git Workflow | references/git-workflows.md | — | | Testing | references/testing-patterns.md | pr-review-toolkit:pr-test-analyzer | | Supabase | references/supabase-patterns.md | pr-review-toolkit:type-design-analyzer | | Deployment | references/deployment-patterns.md | — | | Browser Tools | references/browser-automation.md | — | | Versioning | references/version-management.md | — |

Framework Rules

| Framework | Rule File | Auto-Review Agent | |-----------|-----------|-------------------| | TypeScript | rules/typescript.md | pr-review-toolkit:type-design-analyzer | | Next.js | rules/nextjs.md | feature-dev:code-reviewer | | React | rules/react.md | react-doctor skill | | Supabase | rules/supabase.md | feature-dev:code-reviewer | | Security | rules/security.md | pr-review-toolkit:silent-failure-hunter |

Templates

| Template | Purpose | |----------|---------| | templates/CLAUDE.md.template | Project configuration starter | | templates/settings.json.template | Permission configuration | | templates/project-plan.md.template | Project planning document | | templates/implementation-plan.md.template | Technical implementation plan | | templates/code-review.md.template | Code review summary | | templates/changelog.md.template | Project changelog |

---

Automated Quality Gates

After completing a feature or significant code change, run these specialized agents to catch issues that manual review misses. Launch them in parallel (single message, multiple Agent tool calls).

Quick Review (3 agents, parallel)

For fast feedback after any code change:

Agent(subagent_type="feature-dev:code-reviewer", prompt="Review changes for bugs, security, conventions...")
Agent(subagent_type="pr-review-toolkit:silent-failure-hunter", prompt="Check error handling in changes...")
Agent(subagent_type="pr-review-toolkit:code-simplifier", prompt="Simplify recently modified code...")

Full Review (5 agents, parallel)

Before merge or PR creation — comprehensive quality check:

Agent(subagent_type="feature-dev:code-reviewer", prompt="Review for bugs, security, conventions...")
Agent(subagent_type="pr-review-toolkit:silent-failure-hunter", prompt="Check error handling...")
Agent(subagent_type="pr-review-toolkit:type-design-analyzer", prompt="Review type design quality...")
Agent(subagent_type="pr-review-toolkit:comment-analyzer", prompt="Check comment accuracy...")
Agent(subagent_type="pr-review-toolkit:pr-test-analyzer", prompt="Review test coverage gaps...")

Skill Integration Points

Invoke these skills at key moments:

| Moment | Skill | Purpose | |--------|-------|---------| | After UI changes | react-doctor | Catch React anti-patterns, hooks issues | | After writing tests | full-test-coverage | Verify test pyramid coverage | | After code changes | smart-test | Run only relevant tests (fast feedback) | | Before merge | code-review | Full structured review | | Before PR | pr-review-toolkit:review-pr | Comprehensive PR review |

---

Usage

Starting a New Project

1. Copy templates/CLAUDE.md.template to your project root as CLAUDE.md
2. Customize sections for your stack
3. Reference specific rules: ~/.claude/skills/secret-sauce/rules/typescript.md

Setting Up Permissions

1. Copy templates/settings.json.template to .claude/settings.json
2. Adjust permissions for your workflow

Project Documentation

Use templates for consistent project documentation:

• project-plan.md.template for planning
• implementation-plan.md.template for technical specs
• code-review.md.template for reviews

Codebase Exploration

Use specialized agents to understand an existing codebase:

# Quick exploration
Agent(subagent_type="Explore", prompt="Find all API endpoints and their patterns...")

# Deep analysis
Agent(subagent_type="feature-dev:code-explorer", prompt="Trace auth flow end-to-end...")

# Architecture understanding
Agent(subagent_type="feature-dev:code-architect", prompt="Design implementation for <feature>...")

---

Key Patterns

CLAUDE.md Structure

Every project CLAUDE.md should include:

1. YAML frontmatter (title, status, owner, tags)
2. Quick Reference section with key commands
3. Active/Pending/Completed projects
4. Stack-specific guidelines
5. Development patterns

Git Workflow

• Commit format: <type>(<scope>): <description>
• Never commit without confirmation
• Branch naming: feature/<name>, fix/<name>
• PR template with summary and test plan

Centralization Pattern

All configuration in @/config:

import { env, isProduction, getServiceUrl } from '@/config';

Configuration Hierarchy

1. Database configuration (system_configuration table)
2. Environment variables (.env.local)
3. Hardcoded defaults

Secrets (API keys) → .env.local only Configs (models, URLs) → Database with fallback

Testing Standards

• Target: >90% coverage
• Prefer Vitest for new projects (fast, ESM-native); Jest for existing projects
• Use 30s timeout for ML/AI operations
• Add new test directories to test runners
• Security tests required for auth/validation
• After writing tests → invoke smart-test skill for intelligent test selection

AI Flow Pattern

1. Zod schemas for input/output
2. Prompt builder functions
3. OpenAI SDK v6 with zodResponseFormat() — or Anthropic SDK with structured outputs
4. Error handling with Result types
5. Server action wrapper
6. After implementing → dispatch pr-review-toolkit:silent-failure-hunter to catch swallowed errors in AI error handling

Data Fetching

• Always pass signal to fetch calls
• Use isAbortError() to handle cancellation
• Memoize fetch options to prevent refetches
• Use usePolling for dashboards with visibility-aware intervals

Security Checklist

• Strict TypeScript (no any)
• Zod input validation
• Safe property access: Object.prototype.hasOwnProperty.call()
• XSS prevention on all user inputs
• Rate limiting in API routes
• After security-sensitive changes → dispatch pr-review-toolkit:silent-failure-hunter