agents-inc 0.152.0 → 0.153.0

package/dist/src/agents/pattern/pattern-scout/playbook.md

@@ -1,1806 +0,0 @@
-## Pattern Scouting Scope Requirements
-
-<scope_requirements>
-**CRITICAL: Production monorepos document 10-15 major categories beyond code patterns.**
-
-Your extraction MUST cover AT LEAST:
-
-1. **Code Conventions** (component patterns, types, naming)
-2. **Package Architecture** (workspace organization, dependencies)
-3. **State Management** (server vs client, React Query, Zustand)
-4. **Testing Standards** (unit, integration, E2E, coverage)
-5. **Design System** (3-tier tokens, accessibility)
-6. **Build & Tooling** (Turborepo, linting, pre-commit)
-7. **CI/CD Standards** (pipelines, affected detection)
-8. **Environment Management** (variables, secrets, configs)
-9. **Architecture Decisions** (ADRs capturing WHY)
-10. **AI Optimization** (AGENTS.md, CLAUDE.md, llms.txt)
-
-**Why this matters:**
-
-Production monorepos from Google, Vercel, Shopify document far more than code patterns. Without comprehensive coverage, you'll miss critical standards that prevent:
-
-- Dependency chaos (package architecture)
-- Inconsistent testing (testing standards)
-- AI agents violating conventions (AGENTS.md)
-- Performance issues (state management separation)
-- Design system drift (token structure)
-
-**This is non-negotiable for pattern scouting agents.**
-</scope_requirements>
-
----
-
-## Pattern Scouting Investigation Protocol
-
-<extraction_investigation>
-**Reference the 10+ major categories defined in Pattern Scouting Scope Requirements above.**
-
-Your extraction MUST systematically investigate:
-
-### Required Investigation Steps
-
-**Phase 1: Monorepo Structure**
-
-```bash
-# Understand workspace organization
-cat package.json | grep -A 10 "workspaces"
-cat turbo.json || cat nx.json || echo "No monorepo tool config"
-ls -la packages/ apps/ || echo "Non-standard structure"
-find . -name "package.json" -type f | head -20
-
-# Package dependencies
-grep -r "workspace:" --include="package.json" | head -10
-grep -r "@repo/" --include="*.tsx" --include="*.ts" | wc -l
-```
-
-**Phase 2: Code Patterns**
-
-```bash
-# State management
-grep -r "useQuery" --include="*.tsx" | wc -l
-grep -r "QueryClient" --include="*.ts" | head -5
-grep -r "create(" --include="*.ts" | grep -i store | head -5
-grep -r "useContext\|createContext" --include="*.tsx" | wc -l
-
-# Next.js patterns
-find . -name "page.tsx" -o -name "layout.tsx" | head -10
-grep -r "getServerSideProps\|getStaticProps" --include="*.tsx" | wc -l
-
-# Component architecture
-find . -name "*.tsx" -type f | head -20
-grep -r "interface.*Props" --include="*.tsx" | head -10
-```
-
-**Phase 3: Design System**
-
-```bash
-# CSS variables and tokens
-grep -r "var(--" --include="*.css" --include="*.scss" | head -20
-find . -name "*token*" -o -name "*theme*" | head -10
-grep -r "--base-\|--semantic-\|--component-" --include="*.css" | wc -l
-
-# Accessibility
-grep -r "aria-\|role=" --include="*.tsx" | wc -l
-find . -name "*a11y*" -o -name "*accessibility*"
-```
-
-**Phase 4: Testing Infrastructure**
-
-```bash
-# Test files and patterns
-find . -name "*.test.ts*" -o -name "*.spec.ts*" | wc -l
-cat jest.config.js || cat vitest.config.ts || echo "No test config found"
-find . -name "playwright.config.ts" -o -name "cypress.config.ts"
-grep -r "describe\|it\|test" --include="*.test.ts*" | head -10
-
-# Coverage
-cat package.json | grep -A 5 "coverage"
-```
-
-**Phase 5: Build & Tooling**
-
-```bash
-# Build configuration
-cat turbo.json | head -50 || echo "No Turborepo"
-cat .eslintrc* || cat eslint.config.js || cat biome.json || echo "No linter config"
-cat .prettierrc* || echo "No Prettier config"
-cat .husky/pre-commit || echo "No pre-commit hooks"
-
-# Environment handling
-find . -name ".env*" | head -10
-grep -r "process.env" --include="*.ts" --include="*.tsx" | wc -l
-```
-
-**Phase 6: Documentation & Standards**
-
-```bash
-# Existing documentation
-find . -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "llms.txt"
-find . -name "ADR*" -o -name "decisions/" -type d
-cat CONTRIBUTING.md || cat docs/CONTRIBUTING.md || echo "No contribution guide"
-ls -la .github/workflows/ | head -10
-```
-
-**Phase 7: Extract Concrete Examples**
-
-- Read 5-10 key files per category
-- Note line numbers for examples
-- Document variations and edge cases
-- Identify anti-patterns
-- Count pattern frequency (3+ instances minimum)
-
-**Never document patterns based on assumptions. Always verify with actual code.**
-</extraction_investigation>
-
-## Comprehensive Extraction Focus Areas
-
-Production monorepos from Google, Vercel, Shopify document far more than code patterns. Extract ALL of these categories.
-
-### 1. Package Architecture & Workspace Organization
-
-<extraction_focus area="package-architecture">
-**CRITICAL IMPORTANCE:** Without documented package boundaries, monorepos become tangled dependency graphs.
-
-**What to extract:**
-
-- Workspace structure (packages/, apps/, tools/)
-- Package naming conventions (@repo/package-name, @app/name)
-- Package classification system (type:feature, type:ui, type:data-access, type:util)
-- Dependency constraints and boundaries
-- Internal package imports (workspace protocol vs path aliases)
-- Versioning strategy (Changesets, Lerna, manual)
-- Package.json conventions across workspace
-
-**Red flags to document:**
-
-- Circular dependencies between packages
-- Apps depending on other apps
-- Inconsistent naming (@repo vs @company vs no prefix)
-- Path aliases (@/) used instead of package names
-- Missing dependency constraints allowing any-imports-any
-
-**Example investigation:**
-
-```bash
-# Find workspace protocol usage
-grep -r '"workspace:\*"' --include="package.json"
-
-# Check for path alias abuse
-grep -r '@/' --include="*.ts*" | wc -l
-
-# Dependency analysis
-npx dependency-cruiser packages/
-```
-
-</extraction_focus>
-
----
-
-### 2. Testing Standards (Unit, Integration, E2E)
-
-<extraction_focus area="testing">
-**CRITICAL IMPORTANCE:** "Write tests" is useless. Document WHAT to test, HOW to structure, and coverage requirements.
-
-**What to extract:**
-
-- Test file naming conventions (_.test.ts vs _.spec.ts)
-- Test organization (tests/ vs **tests** vs co-located)
-- What requires unit tests (business logic, pure functions, hooks)
-- What doesn't need tests (types, simple components, mocks)
-- Integration test patterns
-- E2E test structure (Playwright/Cypress)
-- Mock data location and conventions
-- Test configuration inheritance (base configs)
-- Coverage requirements per package
-- Test running commands (single file vs full suite)
-
-**Red flags to document:**
-
-- No tests for critical business logic
-- Testing implementation details instead of behavior
-- Brittle tests that break on refactors
-- E2E tests without proper waits/assertions
-- Mock data that doesn't match API contracts
-
-**Example investigation:**
-
-```bash
-# Test coverage
-find . -name "*.test.ts*" -o -name "*.spec.ts*" | wc -l
-
-# Test patterns
-grep -r "describe\|it\|test" --include="*.test.ts" | head -20
-
-# E2E setup
-cat playwright.config.ts || cat cypress.config.ts
-```
-
-</extraction_focus>
-
----
-
-### 3. State Management Separation
-
-<extraction_focus area="state-management">
-**CRITICAL IMPORTANCE:** Mixing server state (React Query) with client state (Zustand) without guidelines creates performance issues.
-
-**What to extract:**
-
-- Server state patterns (React Query, SWR, Apollo)
-- Client state patterns (Zustand, Context, Jotai, Valtio)
-- Query key structure and factories
-- Cache invalidation strategies
-- Optimistic update patterns
-- State persistence approaches
-- SSR/hydration handling
-- When to use which state solution
-
-**Red flags to document:**
-
-- Server data stored in Zustand/Context
-- UI state fetched via useQuery
-- Inconsistent query key formats
-- Missing cache invalidation after mutations
-- Race conditions in mutations
-
-**Example investigation:**
-
-```bash
-# React Query usage
-grep -r "queryKey:" --include="*.ts*" | head -20
-
-# Zustand stores
-grep -r "create<" --include="*.ts" | grep -i store
-
-# Cache invalidation
-grep -r "invalidateQueries\|refetchQueries" --include="*.ts*"
-```
-
-</extraction_focus>
-
----
-
-### 4. Design System Token Structure
-
-<extraction_focus area="design-system">
-**CRITICAL IMPORTANCE:** Flat CSS variables become unmaintainable. Production teams use 3-tier token systems.
-
-**What to extract:**
-
-- Token architecture (base → semantic → component tiers)
-- Naming conventions (GitHub Primer, Shopify Polaris patterns)
-- Color system (primitives, semantic, component-specific)
-- Spacing system (8px grid, t-shirt sizes, golden ratio)
-- Typography scale (sizes, weights, line heights)
-- Theme implementation (light/dark mode)
-- Component token patterns
-- When to create new tokens vs use existing
-
-**Red flags to document:**
-
-- Hardcoded colors/spacing in components
-- Flat token structure without semantic layer
-- Inconsistent naming patterns
-- Missing fallback values
-- Theme switching breaking components
-
-**Example investigation:**
-
-```bash
-# Token structure
-grep -r "--base-\|--semantic-\|--component-" --include="*.css"
-
-# Hardcoded values
-grep -r "color: #\|margin: [0-9]" --include="*.tsx"
-
-# Theme implementation
-find . -name "*theme*" -o -name "*tokens*"
-```
-
-</extraction_focus>
-
----
-
-### 5. Accessibility Standards
-
-<extraction_focus area="accessibility">
-**CRITICAL IMPORTANCE:** WCAG compliance requires specific, documented patterns per component type.
-
-**What to extract:**
-
-- Keyboard navigation patterns
-- ARIA patterns per component type
-- Focus management strategies
-- Screen reader testing approach
-- Color contrast requirements (4.5:1 text, 3:1 UI)
-- Touch target sizes (44x44px minimum)
-- Testing tools and automation (axe, jest-axe)
-- Accessible name calculation
-- Skip links and landmarks
-
-**Red flags to document:**
-
-- Interactive elements without keyboard support
-- Missing ARIA labels on icon buttons
-- Insufficient color contrast
-- Focus indicators removed with CSS
-- Inaccessible custom controls
-
-**Example investigation:**
-
-```bash
-# ARIA usage
-grep -r "aria-\|role=" --include="*.tsx" | wc -l
-
-# Accessibility testing
-grep -r "toHaveNoViolations\|axe" --include="*.test.ts*"
-
-# Focus management
-grep -r "focus\|tabIndex" --include="*.tsx" | head -20
-```
-
-</extraction_focus>
-
----
-
-### 6. Build System & Tooling Configuration
-
-<extraction_focus area="build-tooling">
-**CRITICAL IMPORTANCE:** Turborepo/Nx won't optimize without proper configuration documentation.
-
-**What to extract:**
-
-- Task pipeline configuration (dependsOn, outputs, inputs)
-- Caching strategies (what gets cached, cache keys)
-- Environment variable handling (env, passThroughEnv, globalEnv)
-- Build tool choice and rationale (Turborepo, Nx, Lerna)
-- Linting setup (ESLint, Biome)
-- Formatting configuration (Prettier, Biome)
-- Pre-commit hooks (Husky, lint-staged)
-- Performance targets (build times, cache hit ratios)
-- Remote caching configuration
-
-**Red flags to document:**
-
-- Missing task dependencies causing build failures
-- Incorrect cache inputs missing source files
-- Environment variables not declared properly
-- Slow builds that could be parallelized
-- Inconsistent linting across packages
-
-**Example investigation:**
-
-```bash
-# Turborepo/Nx config
-cat turbo.json || cat nx.json
-
-# Linting
-cat .eslintrc* || cat biome.json
-
-# Pre-commit
-cat .husky/pre-commit || cat .git/hooks/pre-commit
-```
-
-</extraction_focus>
-
----
-
-### 7. CI/CD Pipeline Standards
-
-<extraction_focus area="cicd">
-**CRITICAL IMPORTANCE:** Inefficient CI wastes minutes and dollars. Document optimization strategies.
-
-**What to extract:**
-
-- Pipeline configuration (GitHub Actions, GitLab CI, CircleCI)
-- Affected project detection strategies
-- Parallel job execution patterns
-- Remote caching setup
-- Secrets management
-- Branch deployment strategies
-- Quality gates and coverage requirements
-- Pipeline performance metrics
-- Deployment workflows
-
-**Red flags to document:**
-
-- Building entire monorepo on every change
-- Missing affected detection
-- Sequential jobs that could run parallel
-- Secrets hardcoded in workflows
-- No quality gates before merging
-
-**Example investigation:**
-
-```bash
-# CI configuration
-ls -la .github/workflows/ || ls -la .gitlab-ci.yml
-
-# Affected detection
-grep -r "filter=\|--affected" .github/workflows/
-
-# Remote caching
-grep -r "TURBO_TOKEN\|NX_CLOUD_AUTH_TOKEN" .github/workflows/
-```
-
-</extraction_focus>
-
----
-
-### 8. Environment Variable Management
-
-<extraction_focus area="environment">
-**CRITICAL IMPORTANCE:** Environment variables are #1 source of "works on my machine" problems.
-
-**What to extract:**
-
-- File hierarchy (.env.defaults, .env, .env.local, .env.production)
-- Naming conventions (NEXT*PUBLIC*, VITE*, PUBLIC*)
-- Variable organization by package
-- Which variables affect cache keys
-- Security classification (public vs secret)
-- Loading order and precedence
-- Secrets management approach
-- How to add new variables
-
-**Red flags to document:**
-
-- Secrets committed to repository
-- Inconsistent naming patterns
-- Environment variables not in template
-- Missing .env.defaults causing failures
-- Unclear which variables affect which packages
-
-**Example investigation:**
-
-```bash
-# Environment files
-find . -name ".env*" | head -10
-
-# Environment usage
-grep -r "process.env\|import.meta.env" --include="*.ts*" | head -20
-
-# Turborepo env config
-cat turbo.json | grep -A 10 "env\|globalEnv"
-```
-
-</extraction_focus>
-
----
-
-### 9. Architecture Decision Records (ADRs)
-
-<extraction_focus area="adrs">
-**CRITICAL IMPORTANCE:** Without ADRs, no one remembers WHY decisions were made 6 months later.
-
-**What to extract:**
-
-- ADR template (MADR is 2025 standard)
-- ADR file organization (docs/decisions/, adr/)
-- Numbering convention (0001-title.md, YYYYMMDD-title.md)
-- Decision types worth recording
-- Review and approval process
-- How to supersede old decisions
-- Tooling (adr-tools, adr-log)
-
-**Decisions worth recording:**
-
-- Technology choices (Turborepo vs Nx vs Lerna)
-- Package organization patterns
-- Testing framework selection
-- State management approach
-- Build tool choices
-- Deployment strategies
-- Breaking API changes
-- Security decisions
-
-**Example investigation:**
-
-```bash
-# Find ADRs
-find . -name "ADR*" -o -name "adr-*" -o -path "*/decisions/*"
-
-# ADR structure
-cat docs/decisions/0001-* || echo "No ADRs found"
-```
-
-</extraction_focus>
-
----
-
-### 10. AI Agent Optimization (AGENTS.md)
-
-<extraction_focus area="ai-optimization">
-**CRITICAL IMPORTANCE:** AI agents need explicit instructions. Without AGENTS.md, they violate conventions.
-
-**What to extract:**
-
-- AGENTS.md structure and content
-- CLAUDE.md for Claude Code memory
-- llms.txt for AI navigation
-- Tech stack summary
-- Do's and Don'ts for AI generation
-- Safe commands (file-scoped, fast feedback)
-- Commands requiring confirmation
-- Common pitfalls to avoid
-- Project-specific patterns
-
-**AGENTS.md sections:**
-
-- Tech stack summary
-- Do's and Don'ts
-- Commands (file-scoped for speed)
-- Safety and permissions
-- Code examples
-- Testing approach
-
-**Example investigation:**
-
-```bash
-# Find AI documentation
-find . -name "AGENTS.md" -o -name "CLAUDE.md" -o -name "llms.txt"
-
-# AI-relevant patterns
-cat AGENTS.md || echo "No AI documentation found"
-```
-
-</extraction_focus>
-
----
-
-### 11. React Query Patterns (Detailed)
-
-<extraction_focus area="react-query">
-**What to extract:**
-
-- Query key structure (hierarchical factories)
-- Custom hooks patterns (wrapping useQuery/useMutation)
-- Error handling strategies
-- Retry configuration
-- Cache time and stale time defaults
-- Optimistic updates
-- Loading and error state management
-- Query client configuration
-- Prefetching strategies
-- Infinite queries
-
-**Example query key factory:**
-
-```typescript
-const postsQueryKeys = {
-  all: ["posts"] as const,
-  lists: () => [...postsQueryKeys.all, "list"] as const,
-  list: (filters: Filters) => [...postsQueryKeys.lists(), { filters }] as const,
-  details: () => [...postsQueryKeys.all, "detail"] as const,
-  detail: (id: number) => [...postsQueryKeys.details(), id] as const,
-};
-```
-
-**Example investigation:**
-
-```bash
-# Query key patterns
-grep -r "queryKey:" --include="*.ts*" | head -20
-
-# Custom hooks
-grep -r "useQuery\|useMutation" --include="*.ts*" | head -10
-
-# Cache configuration
-grep -r "staleTime\|cacheTime" --include="*.ts*"
-```
-
-</extraction_focus>
-
----
-
-### 12. Next.js Conventions (Detailed)
-
-<extraction_focus area="nextjs">
-**What to extract:**
-
-- App Router vs Pages Router usage
-- File-based routing patterns
-- Data fetching approaches (Server Components, Client Components)
-- API route organization
-- Middleware usage
-- Metadata API patterns
-- Image optimization conventions
-- Font optimization
-- Environment variable handling (NEXT*PUBLIC*)
-- Build configuration (next.config.js)
-
-**Example investigation:**
-
-```bash
-# Routing structure
-find . -name "page.tsx" -o -name "layout.tsx" | head -10
-
-# Data fetching
-grep -r "use client\|use server" --include="*.tsx" | wc -l
-
-# API routes
-find . -path "*/api/*" -name "route.ts" | head -10
-
-# Middleware
-find . -name "middleware.ts"
-```
-
-</extraction_focus>
-
----
-
-### 13. Component Architecture Patterns
-
-<extraction_focus area="components">
-**What to extract:**
-
-- Component composition patterns
-- Props interface conventions
-- Children and render prop usage
-- Compound component patterns
-- HOCs and wrapper components
-- Component file structure
-- Co-location strategies (tests, styles)
-- Atomic design implementation (if used)
-- Component library organization
-
-**Example investigation:**
-
-```bash
-# Component patterns
-find . -name "*.tsx" -type f | head -20
-
-# Props interfaces
-grep -r "interface.*Props" --include="*.tsx" | head -10
-
-# Composition patterns
-grep -r "children:" --include="*.tsx" | head -10
-
-# Compound components
-grep -r "Context\|Provider" --include="*.tsx" | wc -l
-```
-
-</extraction_focus>
-
----
-
-### 14. Type Definition Standards
-
-<extraction_focus area="types">
-**What to extract:**
-
-- Interface vs type usage patterns
-- Generic type conventions
-- Utility type usage (Pick, Omit, Partial)
-- Type inference patterns
-- API response type definitions
-- Shared type organization
-- Discriminated unions
-- Type guards and narrowing
-
-**Example investigation:**
-
-```bash
-# Type patterns
-grep -r "interface\|type " --include="*.ts" | head -20
-
-# Type utilities
-grep -r "Pick<\|Omit<\|Partial<" --include="*.ts*" | wc -l
-
-# Generics
-grep -r "<T\|<T,\|<T extends" --include="*.ts*" | head -10
-
-# Type guards
-grep -r "is " --include="*.ts" | grep ":" | head -10
-```
-
-</extraction_focus>
-
----
-
-### 15. Mock Data Patterns
-
-<extraction_focus area="mock-data">
-**What to extract:**
-
-- Mock data structure and organization
-- Factory functions or generators
-- Realistic vs minimal mocks
-- Mock data reuse patterns
-- Integration with testing
-- Development mode data loading
-- MSW (Mock Service Worker) usage
-- Mock vs stub vs fake distinctions
-
-**Example investigation:**
-
-```bash
-# Mock data location
-find . -name "*mock*" -o -name "*fixture*" | head -10
-
-# Mock patterns
-grep -r "mockData\|fixture\|factory" --include="*.ts" | head -10
-
-# MSW handlers
-find . -name "*handlers*" -o -name "*mocks/server*"
-
-# Development data
-grep -r "NODE_ENV.*development" --include="*.ts*" | head -5
-```
-
-</extraction_focus>
-
----
-
-<retrieval_strategy>
-
-## Retrieval Strategy
-
-**Just-in-time loading for pattern extraction:**
-
-```
-Need to find files to analyze?
-├── Know exact filename → Read directly
-├── Know pattern (*.tsx, *.test.ts) → Glob
-└── Need to understand directory structure → Glob with broader pattern
-
-Need to find pattern instances?
-├── Know exact pattern → Grep with exact string
-├── Know pattern structure → Grep with regex
-└── Need frequency count → Grep with count option
-
-Progressive Exploration:
-1. Glob to find relevant file paths
-2. Grep to count pattern frequency across files
-3. Read specific files for detailed analysis (file:line references)
-```
-
-**Load skills dynamically** when comparing extracted patterns against documented standards.
-</retrieval_strategy>
-
----
-
-**Additional Anti-Over-Engineering Check for Pattern Scouting:**
-
-Before documenting a pattern, ask:
-
-1. **Is it actually used?** (Not just defined once and forgotten)
-2. **Does it solve a real problem?** (Not just clever engineering)
-3. **Is it consistent?** (3+ instances, not a one-off experiment)
-4. **Would someone understand it without me?** (Self-documenting patterns only)
-
-**Skip patterns that:**
-
-- Only appear once or twice
-- Are overly abstract without clear benefit
-- Were clearly experiments that weren't adopted
-- Require extensive explanation to understand
-
-**We want standards that emerged naturally, not aspirational ones.**
-
-## Comprehensive Output Format
-
-<output_format>
-Create a file at `./extracted-standards.md` with this structure:
-
-```markdown
-# [Project Name] - Comprehensive Standards & Patterns
-
-**Extraction Date:** [YYYY-MM-DD]
-**Codebase Version:** [commit hash if available]
-**Monorepo Tool:** [Turborepo/Nx/Lerna/Yarn Workspaces]
-**Confidence Level:** [High/Medium/Low] - based on pattern consistency
-
----
-
-## Table of Contents
-
-1. [Package Architecture](#1-package-architecture)
-2. [Code Conventions](#2-code-conventions)
-3. [State Management](#3-state-management)
-4. [Testing Standards](#4-testing-standards)
-5. [Design System](#5-design-system)
-6. [Accessibility](#6-accessibility)
-7. [Build & Tooling](#7-build--tooling)
-8. [CI/CD Pipelines](#8-cicd-pipelines)
-9. [Environment Management](#9-environment-management)
-10. [Architecture Decisions](#10-architecture-decisions)
-11. [AI Agent Optimization](#11-ai-agent-optimization)
-12. [Performance Standards](#12-performance-standards)
-13. [Security Patterns](#13-security-patterns)
-14. [Git Workflow](#14-git-workflow)
-15. [Anti-Patterns Observed](#15-anti-patterns-observed)
-16. [Quick Reference for AI](#16-quick-reference-for-ai)
-
----
-
-## 1. Package Architecture
-
-### 1.1 Workspace Structure
-
-**Pattern:** [Describe workspace organization]
-**Frequency:** Found in X packages
-**Example:**
-```
-
-packages/
-├── ui/ # type:ui - Shared components
-├── utils/ # type:util - Pure functions
-apps/
-├── web/ # Next.js application
-
-`````
-**Rationale:** [Why this organization works]
-
-### 1.2 Package Naming Conventions
-
-**Pattern:** All internal packages use `@repo/` prefix
-**Example:**
-```json
-{
-  "name": "@repo/ui",
-  "dependencies": {
-    "@repo/utils": "workspace:*"
-  }
-}
-```
-
-**Rationale:** [Why workspace protocol is used]
-
-### 1.3 Dependency Boundaries
-
-**Pattern:** [Document ESLint rules or Nx constraints]
-**Example:**
-
-```javascript
-// eslintrc.js:45-60
-{
-  '@nx/enforce-module-boundaries': ['error', {
-    depConstraints: [
-      {
-        sourceTag: 'type:ui',
-        onlyDependOnLibsWithTags: ['type:ui', 'type:util']
-      }
-    ]
-  }]
-}
-```
-
-**Gotchas:** [Circular dependency issues observed]
-
-### 1.4 Import Conventions
-
-**Pattern:** Use package names, not path aliases
-**Example:**
-
-```typescript
-// Good: packages/web/src/components/Button.tsx
-import { cn } from "@repo/utils";
-
-// Bad (avoid):
-import { cn } from "@/lib/utils";
-```
-
-**Rationale:** [Better IDE support, clearer dependencies]
-
-### 1.5 Versioning Strategy
-
-**Pattern:** Changesets for automated versioning
-**Tools:** [@changesets/cli](https://github.com/changesets/changesets)
-**Usage:** [How team manages package versions]
-
----
-
-## 2. Code Conventions
-
-### 2.1 Component Architecture
-
-**Pattern:** [Composition patterns]
-**Example:**
-
-```typescript
-// packages/ui/src/Button.tsx:12-45
-interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
-  variant?: 'primary' | 'secondary';
-  size?: 'sm' | 'md' | 'lg';
-}
-
-export const Button = ({ variant = 'primary', size = 'md', ...props }: ButtonProps) => {
-  return <button className={cn(styles[variant], styles[size])} {...props} />
-}
-```
-
-**Rationale:** [Extensible, type-safe props]
-
-### 2.2 File and Directory Naming
-
-**Pattern:** [kebab-case, PascalCase, etc.]
-**Components:** PascalCase (`Button.tsx`, `UserProfile.tsx`)
-**Utilities:** kebab-case (`format-date.ts`, `api-client.ts`)
-**Tests:** Co-located with implementation (`Button.test.tsx`)
-
-### 2.3 Import/Export Patterns
-
-**Pattern:** [Named exports vs default exports]
-**Example:**
-
-```typescript
-// Prefer named exports for tree-shaking
-export { Button } from "./Button";
-export { Input } from "./Input";
-
-// Avoid default exports in libraries
-export default Button; // ❌
-```
-
-### 2.4 Type Definitions
-
-**Pattern:** Interface for object shapes, type for unions/intersections
-**Example:**
-
-```typescript
-// Interface for extending
-interface UserProps {
-  name: string;
-  email: string;
-}
-
-// Type for unions
-type Status = "active" | "inactive" | "pending";
-```
-
----
-
-## 3. State Management
-
-### 3.1 Server State vs Client State
-
-**Strategy:** Strict separation
-**Server State:** React Query for ALL server data
-**Client State:** Zustand for UI state, filters, preferences
-
-### 3.2 React Query Patterns
-
-#### 3.2.1 Query Key Structure
-
-**Pattern:** Hierarchical query key factories
-**Example:**
-
-```typescript
-// packages/api-client/src/posts/queries.ts:8-15
-export const postsQueryKeys = {
-  all: ["posts"] as const,
-  lists: () => [...postsQueryKeys.all, "list"] as const,
-  list: (filters: Filters) => [...postsQueryKeys.lists(), { filters }] as const,
-  details: () => [...postsQueryKeys.all, "detail"] as const,
-  detail: (id: number) => [...postsQueryKeys.details(), id] as const,
-};
-```
-
-**Rationale:** Enables prefix invalidation, type-safe keys
-
-#### 3.2.2 Custom Query Hooks
-
-**Pattern:** [Wrap useQuery in custom hooks]
-**Example:**
-
-```typescript
-// packages/api-client/src/posts/hooks.ts:20-28
-export const usePost = (id: number) => {
-  return useQuery({
-    queryKey: postsQueryKeys.detail(id),
-    queryFn: () => fetchPost(id),
-    staleTime: 5 * 60 * 1000, // 5 minutes
-  })
-}
-```
-
-#### 3.2.3 Cache Invalidation
-
-**Pattern:** Prefix matching after mutations
-**Example:**
-
-```typescript
-// After creating a post
-queryClient.invalidateQueries({
-  queryKey: ["posts", "list"],
-  exact: false, // Invalidates all list queries
-});
-```
-
-### 3.3 Zustand Patterns
-
-**Pattern:** [When and how to use Zustand]
-**Example:**
-
-```typescript
-// packages/ui/src/stores/filter-store.ts:5-12
-export const useFilterStore = create<FilterState>((set) => ({
-  filters: { status: "all" },
-  setFilters: (filters) => set({ filters }),
-  resetFilters: () => set({ filters: { status: "all" } }),
-}));
-```
-
-**Use cases:** UI state, modal state, filters, preferences
-
----
-
-## 4. Testing Standards
-
-### 4.1 Test Organization
-
-**Structure:** Co-located tests
-**Naming:** `*.test.ts` for unit, `*.spec.ts` for integration
-**Location:** Same directory as implementation
-
-### 4.2 Unit Testing
-
-**Framework:** [Vitest/Jest]
-**What to test:**
-
-- Business logic functions
-- Custom hooks
-- Utility functions
-- Component behavior (not implementation)
-
-**What NOT to test:**
-
-- Type definitions
-- Simple presentational components
-- Third-party libraries
-
-**Example:**
-
-```typescript
-// packages/utils/src/format-date.test.ts:10-18
-describe("formatDate", () => {
-  it("formats ISO date to readable format", () => {
-    expect(formatDate("2025-11-12")).toBe("November 12, 2025");
-  });
-});
-```
-
-### 4.3 Integration Testing
-
-**Strategy:** [API mocking with MSW]
-**Example:**
-
-```typescript
-// packages/api-client/tests/posts.spec.ts:15-25
-import { server } from "../mocks/server";
-
-beforeAll(() => server.listen());
-afterEach(() => server.resetHandlers());
-afterAll(() => server.close());
-```
-
-### 4.4 E2E Testing
-
-**Framework:** [Playwright/Cypress]
-**Coverage:** Critical user flows only
-**Example:**
-
-```typescript
-// apps/web/tests/e2e/checkout.spec.ts:8-20
-test("user can complete checkout", async ({ page }) => {
-  await page.goto("/products");
-  await page.click('[data-testid="add-to-cart"]');
-  await page.click('[data-testid="checkout"]');
-  // ...
-});
-```
-
-### 4.5 Coverage Requirements
-
-**Minimum thresholds:**
-
-- Branches: 80%
-- Functions: 80%
-- Lines: 80%
-- Statements: 80%
-
-**Configuration:**
-
-```json
-// jest.config.base.js:20-25
-{
-  "coverageThreshold": {
-    "global": {
-      "branches": 80,
-      "functions": 80,
-      "lines": 80,
-      "statements": 80
-    }
-  }
-}
-```
-
-### 4.6 Mock Data Patterns
-
-**Location:** `__mocks__/` directory per package
-**Structure:** [Realistic vs minimal mocks]
-**Example:**
-
-```typescript
-// packages/api-client/__mocks__/posts.ts:5-12
-export const mockPost = {
-  id: 1,
-  title: "Test Post",
-  content: "Test content",
-  createdAt: "2025-11-12T00:00:00Z",
-};
-```
-
----
-
-## 5. Design System
-
-### 5.1 Token Architecture
-
-**System:** Three-tier token structure
-**Tiers:**
-
-1. **Base tokens** - Raw values (--base-color-green-500)
-2. **Semantic tokens** - Purpose-driven (--bgColor-success)
-3. **Component tokens** - Component-specific (--button-success-bgColor)
-
-**Example:**
-
-```css
-/* styles/tokens/base.css:1-10 */
-:root {
-  /* Tier 1: Base */
-  --base-color-green-500: #2da44e;
-
-  /* Tier 2: Semantic */
-  --bgColor-success: var(--base-color-green-500);
-
-  /* Tier 3: Component */
-  --button-success-bgColor: var(--bgColor-success);
-}
-```
-
-### 5.2 Color System
-
-**Pattern:** [Naming convention]
-**Scale:** [50, 100, 200, ... 900]
-**Usage:** Never use base tokens directly in components
-
-### 5.3 Spacing System
-
-**Scale:** 8px base unit
-**Tokens:**
-
-```css
---space-1: 0.25rem; /* 4px */
---space-2: 0.5rem; /* 8px */
---space-4: 1rem; /* 16px */
---space-8: 2rem; /* 32px */
-```
-
-### 5.4 Typography
-
-**Scale:** [Size scale and line heights]
-**Example:**
-
-```css
---fontSize-1: 0.75rem; /* 12px */
---fontSize-2: 0.875rem; /* 14px */
---fontSize-3: 1rem; /* 16px */
---lineHeight-default: 1.5;
-```
-
-### 5.5 Theme Implementation
-
-**Approach:** [CSS variables for light/dark mode]
-**Example:**
-
-```css
-[data-theme="light"] {
-  --bgColor-default: white;
-  --fgColor-default: black;
-}
-
-[data-theme="dark"] {
-  --bgColor-default: black;
-  --fgColor-default: white;
-}
-```
-
----
-
-## 6. Accessibility
-
-### 6.1 Keyboard Navigation Standards
-
-**Pattern:** [Document per component type]
-**Example:**
-
-```markdown
-### Button Keyboard Support
-
-- Tab: Moves focus to/from button
-- Space/Enter: Activates button
-- Escape: Closes dialog (if applicable)
-```
-
-### 6.2 ARIA Patterns
-
-**Required ARIA:**
-
-```tsx
-// Icon-only button
-<button aria-label="Close dialog">
-  <CloseIcon />
-</button>
-
-// Toggle button
-<button aria-pressed={isPressed}>
-  Subscribe
-</button>
-```
-
-### 6.3 Color Contrast Requirements
-
-**Standard:** WCAG 2.1 Level AA
-**Requirements:**
-
-- Text: 4.5:1 minimum
-- Large text (18pt+): 3:1 minimum
-- UI components: 3:1 minimum
-
-### 6.4 Testing Approach
-
-**Tools:** axe-core, jest-axe
-**Example:**
-
-```typescript
-import { axe } from 'jest-axe';
-
-test('Button has no a11y violations', async () => {
-  const { container } = render(<Button>Click</Button>);
-  const results = await axe(container);
-  expect(results).toHaveNoViolations();
-});
-```
-
-### 6.5 Touch Target Sizes
-
-**Minimum:** 44×44px for all interactive elements
-**Exception:** Inline text links
-
----
-
-## 7. Build & Tooling
-
-### 7.1 Turborepo Configuration
-
-**Pipeline:**
-
-```json
-// turbo.json:5-20
-{
-  "tasks": {
-    "build": {
-      "dependsOn": ["^build"],
-      "outputs": ["dist/**", ".next/**"],
-      "inputs": ["src/**/*.ts", "src/**/*.tsx"]
-    },
-    "test": {
-      "dependsOn": ["build"],
-      "outputs": ["coverage/**"],
-      "cache": true
-    }
-  }
-}
-```
-
-### 7.2 Linting Configuration
-
-**Tool:** [ESLint/Biome]
-**Configuration:**
-
-```json
-// .eslintrc.json:1-15
-{
-  "extends": ["next/core-web-vitals", "prettier"],
-  "rules": {
-    "@typescript-eslint/no-unused-vars": "error",
-    "@typescript-eslint/no-explicit-any": "warn"
-  }
-}
-```
-
-### 7.3 Formatting
-
-**Tool:** [Prettier/Biome]
-**Settings:**
-
-```json
-{
-  "printWidth": 100,
-  "semi": false,
-  "singleQuote": true,
-  "trailingComma": "es5"
-}
-```
-
-### 7.4 Pre-commit Hooks
-
-**Tool:** Husky + lint-staged
-**Configuration:**
-
-```bash
-# .husky/pre-commit:3-5
-npx lint-staged --concurrent false
-```
-
-```json
-// .lintstagedrc.json:1-5
-{
-  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
-  "*.{json,md}": ["prettier --write"]
-}
-```
-
-### 7.5 Environment Handling
-
-**Turborepo env:**
-
-```json
-{
-  "globalEnv": ["DATABASE_URL"],
-  "env": ["NEXT_PUBLIC_API_URL"]
-}
-```
-
----
-
-## 8. CI/CD Pipelines
-
-### 8.1 GitHub Actions Configuration
-
-**Pattern:** [Affected detection with Turborepo]
-**Example:**
-
-```yaml
-# .github/workflows/ci.yml:15-30
-jobs:
-  build:
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Build affected
-        run: pnpm turbo run build --filter=[HEAD^1]
-
-      - name: Test affected
-        run: pnpm turbo run test --filter=[HEAD^1]
-```
-
-### 8.2 Remote Caching
-
-**Provider:** [Vercel/S3/Custom]
-**Setup:**
-
-```yaml
-env:
-  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
-  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
-```
-
-### 8.3 Quality Gates
-
-**Requirements:**
-
-- All tests pass
-- Coverage thresholds met
-- No linting errors
-- Build succeeds
-
----
-
-## 9. Environment Management
-
-### 9.1 File Hierarchy
-
-**Loading order:**
-
-1. `.env.defaults` - Default values (committed)
-2. `.env` - Local overrides (gitignored)
-3. `.env.local` - Package-specific (gitignored)
-4. `.env.production` - Production values (in CI)
-
-### 9.2 Naming Conventions
-
-**Public variables:** `NEXT_PUBLIC_`, `VITE_`, `PUBLIC_`
-**Secret variables:** Never prefixed with public markers
-
-### 9.3 Template
-
-**Pattern:** Maintain `.env.template` with all variables (no values)
-**Example:**
-
-```bash
-# .env.template:1-10
-DATABASE_URL=
-REDIS_URL=
-NEXT_PUBLIC_API_URL=
-NEXT_PUBLIC_APP_URL=
-```
-
----
-
-## 10. Architecture Decisions
-
-### 10.1 ADR Structure
-
-**Template:** MADR (Markdown Any Decision Records)
-**Location:** `docs/decisions/`
-**Naming:** `NNNN-title-with-dashes.md`
-
-### 10.2 ADR Template
-
-```markdown
-# [Short title of decision]
-
-## Context and Problem Statement
-
-[Describe context and question forcing decision]
-
-## Decision Drivers
-
-- [Driver 1]
-- [Driver 2]
-
-## Considered Options
-
-- [Option 1]
-- [Option 2]
-
-## Decision Outcome
-
-Chosen: [option 1]
-
-### Consequences
-
-- Good: [positive outcome]
-- Bad: [negative consequence]
-
-## Confirmation
-
-[How to verify decision is working]
-```
-
-### 10.3 Decisions Recorded
-
-**Found ADRs:**
-
-- [List any existing ADRs discovered]
-
-**Recommended to document:**
-
-- Technology choices (Turborepo, state management)
-- Package organization rationale
-- Testing framework selection
-- Build tool decisions
-
----
-
-## 11. AI Agent Optimization
-
-### 11.1 AGENTS.md Structure
-
-**Location:** Root of repository
-**Sections:**
-
-- Tech stack summary
-- Do's and Don'ts
-- Commands (file-scoped for fast feedback)
-- Safety and permissions
-
-**Example content:**
-
-````markdown
-# Development Guidelines for AI Agents
-
-## Tech Stack
-
-- **Monorepo:** Turborepo with pnpm workspaces
-- **Frontend:** Next.js 15 (App Router)
-- **State:** React Query + Zustand
-- **Styling:** CSS variables with 3-tier tokens
-
-## Do's
-
-- Use workspace protocol for internal deps
-- Use React Query for ALL server data
-- Use three-tier design token system
-
-## Don'ts
-
-- Don't hardcode colors, use tokens
-- Don't use path aliases, use package names
-- Don't mix server state in Zustand
-
-## Commands (File-Scoped)
-
-```bash
-# Fast feedback commands
-pnpm tsc --noEmit path/to/file.ts
-pnpm prettier --write path/to/file.ts
-pnpm eslint path/to/file.ts
-```
-`````
-
-### 11.2 CLAUDE.md for Memory
-
-**Pattern:** [Project-wide context]
-**Location:** Root + package-level files
-
----
-
-## 12. Performance Standards
-
-### 12.1 Build Performance
-
-**Targets:**
-
-- Full build: < 2 minutes
-- Incremental build: < 30 seconds
-- Cache hit ratio: > 80%
-
-### 12.2 Bundle Size Budgets
-
-**Limits:**
-
-```json
-{
-  "budgets": [
-    {
-      "type": "bundle",
-      "name": "main",
-      "maximumSize": "200kb"
-    }
-  ]
-}
-```
-
-### 12.3 Runtime Performance
-
-**Targets:**
-
-- First Contentful Paint: < 1.8s
-- Largest Contentful Paint: < 2.5s
-- Time to Interactive: < 3.8s
-- Cumulative Layout Shift: < 0.1
-
----
-
-## 13. Security Patterns
-
-### 13.1 Secret Management
-
-**Pattern:** Never commit secrets
-**Tools:** [Environment variables, secret management]
-
-### 13.2 Dependency Security
-
-**Tools:** Dependabot, Snyk
-**Process:** [Automated security updates]
-
-### 13.3 Code Ownership
-
-**File:** CODEOWNERS
-**Pattern:** [Define package owners]
-
----
-
-## 14. Git Workflow
-
-### 14.1 Branch Strategy
-
-**Pattern:** [trunk-based, git-flow, GitHub flow]
-
-### 14.2 Commit Conventions
-
-**Format:** [Conventional Commits]
-**Example:**
-
-```
-feat(ui): add Button component
-fix(api-client): handle network errors
-docs(readme): update installation steps
-```
-
-### 14.3 Code Review Process
-
-**Requirements:**
-
-- [Number of approvals]
-- [Quality checks must pass]
-
----
-
-## 15. Anti-Patterns Observed
-
-### 15.1 [Anti-pattern name]
-
-**What:** [Describe the anti-pattern]
-**Where:** Found in [files]
-**Why problematic:** [Consequences]
-**Better approach:** [What should be done instead]
-
-[Repeat for each anti-pattern discovered]
-
----
-
-## 16. Quick Reference for AI Agents
-
-### Essential Patterns
-
-```typescript
-// Query hook
-export const usePost = (id: number) => {
-  return useQuery({
-    queryKey: ['posts', 'detail', id],
-    queryFn: () => fetchPost(id)
-  })
-}
-
-// Component with tokens
-<button className={styles.primary}>
-  {/* Styles use CSS variables: */}
-  {/* background: var(--button-primary-bgColor); */}
-</button>
-
-// Package imports
-import { Button } from '@repo/ui';
-import { formatDate } from '@repo/utils';
-```
-
-### Critical Do's
-
-- [Top 5 most important do's extracted]
-
-### Critical Don'ts
-
-- [Top 5 most important don'ts extracted]
-
-### File-Scoped Commands (Fast Feedback)
-
-```bash
-# Type check single file
-pnpm tsc --noEmit path/to/file.ts
-
-# Format single file
-pnpm prettier --write path/to/file.ts
-
-# Lint single file
-pnpm eslint path/to/file.ts
-
-# Test single file
-pnpm vitest run path/to/file.test.ts
-```
-
----
-
-## Confidence & Coverage Notes
-
-**High Confidence Patterns:** [List patterns seen 5+ times]
-**Medium Confidence Patterns:** [List patterns seen 3-4 times]
-**Low Confidence Patterns:** [List patterns seen 2 times - needs verification]
-
-**Coverage Gaps:** [Areas where patterns are inconsistent or missing]
-
-**Missing Documentation:**
-
-- [ ] Package architecture not documented
-- [ ] Testing standards undefined
-- [ ] No ADRs found
-- [ ] AGENTS.md missing
-
----
-
-## Implementation Priority
-
-### Immediate (Week 1)
-
-1. Create AGENTS.md
-2. Document package architecture
-3. Define testing standards
-4. Clarify state management separation
-
-### High Priority (Week 2-3)
-
-5. Document design token system
-6. Optimize Turborepo configuration
-7. Setup ADR templates
-8. Improve CI/CD pipelines
-
-### Ongoing
-
-- Keep AGENTS.md updated
-- Record architectural decisions
-- Maintain performance budgets
-- Review and refactor anti-patterns
-
-````
-
-</output_format>
-
----
-
-## Quality Gates
-
-<quality_checks>
-**Coverage Checklist (15+ categories):**
-
-- ✅ Package Architecture
-- ✅ Code Conventions
-- ✅ State Management
-- ✅ Testing Standards
-- ✅ Design System
-- ✅ Accessibility
-- ✅ Build & Tooling
-- ✅ CI/CD
-- ✅ Environment
-- ✅ ADRs
-- ✅ AI Optimization
-- ✅ Performance
-- ✅ Security
-- ✅ Git Workflow
-- ✅ Anti-Patterns
-
-**Quality Standards:**
-
-- ✅ Every pattern has 3+ real examples
-- ✅ All file references include line numbers
-- ✅ Rationale explains WHY, not just WHAT
-- ✅ Anti-patterns have clear consequences
-- ✅ Quick reference is copy-paste ready
-- ✅ Confidence levels are honest
-- ✅ Output is AI-consumable
-- ✅ AGENTS.md section is complete
-- ✅ Priority recommendations exist
-- ✅ Coverage gaps are identified
-
-**Minimum standard:** At least 10 of 15 major categories documented with high confidence patterns.
-</quality_checks>
-
----
-
-## Usage Instructions
-
-To use this agent for comprehensive monorepo pattern scouting:
-
-```bash
-# Comprehensive extraction covering all 15+ categories
-claude --agent @pattern-scout.md "Perform comprehensive monorepo pattern scouting"
-
-# Focused extraction of specific areas
-claude --agent @pattern-scout.md "Extract package architecture and testing standards"
-
-# Validation of existing extracted-standards.md
-claude --agent @pattern-scout.md "Review extracted-standards.md for completeness"
-
-# Update after codebase changes
-claude --agent @pattern-scout.md "Update extracted-standards.md with new patterns"
-````
-
-**What this agent delivers:**
-
-1. Complete `extracted-standards.md` (~8,000-12,000 lines)
-2. Coverage of 15+ major categories
-3. Production-grade standards (Vercel/GitHub/Shopify quality)
-4. AI-optimized format
-5. Actionable implementation plan
-
-**Time investment:**
-
-- Comprehensive extraction: ~6 hours
-- Focused extraction (3-5 categories): ~2 hours
-- Validation/updates: ~30-60 minutes