grimoire-framework 1.0.0

package/.grimoire/product/data/atomic-design-principles.md

@@ -0,0 +1,108 @@
+# Atomic Design Principles
+
+**Source:** Brad Frost's Atomic Design methodology
+**Application:** Atlas component organization
+
+---
+
+## The Five Levels
+
+### Atoms
+**Definition:** Basic building blocks that can't be broken down further.
+
+**Examples:**
+- Button
+- Input
+- Label
+- Icon
+- Heading
+- Text
+
+**Rules:**
+- Standalone, reusable
+- No dependencies on other atoms
+- Uses tokens only (no hardcoded values)
+- Single responsibility
+
+### Molecules
+**Definition:** Groups of atoms functioning together as a unit.
+
+**Examples:**
+- FormField (Label + Input + HelperText)
+- SearchBar (Input + Button)
+- Card Header (Icon + Heading + Text)
+
+**Rules:**
+- Composes atoms (doesn't reimplement)
+- Adds composition logic
+- Atoms remain independent
+
+### Organisms
+**Definition:** Complex UI components composed of molecules and/or atoms.
+
+**Examples:**
+- Navigation (Logo + NavLinks + SearchBar + UserMenu)
+- LoginForm (FormFields + Button + Link)
+- ProductCard (Image + CardHeader + CardBody + Button)
+
+**Rules:**
+- Distinct section of interface
+- Can be reused across templates
+- Manages internal state if needed
+
+### Templates
+**Definition:** Page-level layout without real content.
+
+**Examples:**
+- DashboardLayout
+- ArticleLayout
+- CheckoutFlowLayout
+
+**Rules:**
+- Defines page structure
+- Placeholder content
+- Reusable across pages
+
+### Pages
+**Definition:** Templates with real content.
+
+**Examples:**
+- Homepage
+- Product Detail Page
+- User Dashboard
+
+**Note:** Atlas focuses on atoms → organisms. Pages are application-specific.
+
+---
+
+## Benefits
+
+1. **Consistency:** Reusing atoms ensures UI consistency
+2. **Scalability:** New features built from existing components
+3. **Maintenance:** Fix once, applies everywhere
+4. **Testing:** Test atoms thoroughly, compose with confidence
+5. **Collaboration:** Clear component taxonomy
+
+---
+
+## Atlas Implementation
+
+```
+design-system/
+├── atoms/
+│   ├── Button/
+│   ├── Input/
+│   └── Label/
+├── molecules/
+│   ├── FormField/
+│   └── SearchBar/
+├── organisms/
+│   ├── Navigation/
+│   └── LoginForm/
+└── templates/
+    └── DashboardLayout/
+```
+
+**Atlas builds:** atoms first → molecules → organisms → templates
+
+**Reference:** https://atomicdesign.bradfrost.com/

package/.grimoire/product/data/brainstorming-techniques.md

@@ -0,0 +1,37 @@
+# Brainstorming Techniques Data
+
+## Creative Expansion
+
+1. **What If Scenarios**: Ask one provocative question, get their response, then ask another
+2. **Analogical Thinking**: Give one example analogy, ask them to find 2-3 more
+3. **Reversal/Inversion**: Pose the reverse question, let them work through it
+4. **First Principles Thinking**: Ask "What are the fundamentals?" and guide them to break it down
+
+## Structured Frameworks
+
+5. **SCAMPER Method**: Go through one letter at a time, wait for their ideas before moving to next
+6. **Six Thinking Hats**: Present one hat, ask for their thoughts, then move to next hat
+7. **Mind Mapping**: Start with central concept, ask them to suggest branches
+
+## Collaborative Techniques
+
+8. **"Yes, And..." Building**: They give idea, you "yes and" it, they "yes and" back - alternate
+9. **Brainwriting/Round Robin**: They suggest idea, you build on it, ask them to build on yours
+10. **Random Stimulation**: Give one random prompt/word, ask them to make connections
+
+## Deep Exploration
+
+11. **Five Whys**: Ask "why" and wait for their answer before asking next "why"
+12. **Morphological Analysis**: Ask them to list parameters first, then explore combinations together
+13. **Provocation Technique (PO)**: Give one provocative statement, ask them to extract useful ideas
+
+## Advanced Techniques
+
+14. **Forced Relationships**: Connect two unrelated concepts and ask them to find the bridge
+15. **Assumption Reversal**: Challenge their core assumptions and ask them to build from there
+16. **Role Playing**: Ask them to brainstorm from different stakeholder perspectives
+17. **Time Shifting**: "How would you solve this in 1995? 2030?"
+18. **Resource Constraints**: "What if you had only $10 and 1 hour?"
+19. **Metaphor Mapping**: Use extended metaphors to explore solutions
+20. **Question Storming**: Generate questions instead of answers first
+ 

package/.grimoire/product/data/consolidation-algorithms.md

@@ -0,0 +1,142 @@
+# Pattern Consolidation Algorithms
+
+**Agent:** Brad (Design System Architect)
+**Purpose:** How Brad reduces 176 patterns to 32
+
+---
+
+## Color Clustering (HSL-based)
+
+**Algorithm:** Perceptual similarity in HSL color space
+
+```python
+def cluster_colors(colors, threshold=0.05):
+    """
+    Group colors within 5% HSL difference
+    threshold: 0.05 = 5% difference in H, S, or L
+    """
+    clusters = []
+    for color in colors:
+        hsl = hex_to_hsl(color)
+        found_cluster = False
+
+        for cluster in clusters:
+            cluster_hsl = hex_to_hsl(cluster['primary'])
+            if hsl_distance(hsl, cluster_hsl) < threshold:
+                cluster['members'].append(color)
+                found_cluster = True
+                break
+
+        if not found_cluster:
+            clusters.append({
+                'primary': color,  # Most-used in this cluster
+                'members': [color]
+            })
+
+    return clusters
+```
+
+**Example:**
+```
+Input: #0066CC, #0065CB, #0067CD, #0064CA
+HSL distance: All within 2% of each other
+Output: Cluster → Keep #0066CC (most-used)
+```
+
+**Why HSL not RGB:** Perceptually similar colors cluster better in HSL space.
+
+---
+
+## Button Semantic Analysis
+
+**Algorithm:** Keyword matching + usage frequency
+
+```python
+def analyze_button_semantics(button_classes):
+    """
+    Group buttons by semantic purpose
+    Keywords: primary, main, secondary, default, danger, delete, destructive
+    """
+    semantic_groups = {
+        'primary': [],
+        'secondary': [],
+        'destructive': []
+    }
+
+    for btn_class, usage_count in button_classes:
+        if any(kw in btn_class.lower() for kw in ['primary', 'main', 'cta']):
+            semantic_groups['primary'].append((btn_class, usage_count))
+        elif any(kw in btn_class.lower() for kw in ['secondary', 'default', 'ghost']):
+            semantic_groups['secondary'].append((btn_class, usage_count))
+        elif any(kw in btn_class.lower() for kw in ['danger', 'delete', 'destructive', 'error']):
+            semantic_groups['destructive'].append((btn_class, usage_count))
+
+    # Keep most-used in each group
+    return {
+        group: max(classes, key=lambda x: x[1])[0]
+        for group, classes in semantic_groups.items()
+        if classes
+    }
+```
+
+**Result:** 47 buttons → 3 variants (primary, secondary, destructive)
+
+---
+
+## Spacing Scale Generation
+
+**Algorithm:** Base unit detection + scale building
+
+```python
+def generate_spacing_scale(spacing_values):
+    """
+    Detect base unit (4px or 8px)
+    Build scale from base unit
+    """
+    # Find GCD of all spacing values
+    base_unit = gcd_multiple(spacing_values)
+
+    # Common: 4px or 8px
+    if base_unit not in [4, 8]:
+        base_unit = 4  # Default to 4px
+
+    # Generate scale
+    scale = {
+        'xs': base_unit,
+        'sm': base_unit * 2,
+        'md': base_unit * 4,
+        'lg': base_unit * 6,
+        'xl': base_unit * 8,
+        '2xl': base_unit * 12,
+        '3xl': base_unit * 16
+    }
+
+    return scale
+```
+
+**Example:**
+```
+Input: 2, 4, 6, 8, 12, 16, 20, 24, 32
+Base unit: 4px
+Output: xs=4, sm=8, md=16, lg=24, xl=32, 2xl=48, 3xl=64
+```
+
+---
+
+## Consolidation Targets
+
+**Brad's Targets:**
+- Colors: >85% reduction
+- Buttons: >90% reduction
+- Spacing: >60% reduction
+- Typography: >50% reduction
+- **Overall:** >80% reduction
+
+**Achieved:** Typically 81-86% overall reduction
+
+---
+
+## References
+
+- HSL color space: https://en.wikipedia.org/wiki/HSL_and_HSV
+- Brad Frost patterns: https://bradfrost.com/blog/

package/.grimoire/product/data/database-best-practices.md

@@ -0,0 +1,182 @@
+# Database Best Practices Guide
+
+**Purpose:** Reference guide for database design and implementation patterns
+**Agent:** Dan (Data Engineer)
+**Standard:** Production-ready PostgreSQL/Supabase patterns
+
+---
+
+## SCHEMA DESIGN
+
+### Naming Conventions
+- [ ] Tables: snake_case, plural (e.g., `user_profiles`)
+- [ ] Columns: snake_case, descriptive (e.g., `created_at`, `is_active`)
+- [ ] Primary keys: `id` (UUID preferred) or `{table}_id`
+- [ ] Foreign keys: `{referenced_table}_id`
+- [ ] Indexes: `idx_{table}_{column(s)}`
+- [ ] Constraints: `{table}_{type}_{column}` (e.g., `users_unique_email`)
+
+### Data Types
+- [ ] Use appropriate types (not just VARCHAR for everything)
+- [ ] UUID for primary keys (better distribution, security)
+- [ ] TIMESTAMPTZ for timestamps (timezone-aware)
+- [ ] JSONB for flexible/nested data (not JSON)
+- [ ] ENUM types for fixed value sets
+- [ ] TEXT over VARCHAR (PostgreSQL handles efficiently)
+
+---
+
+## INDEXING STRATEGY
+
+### When to Index
+- [ ] Primary keys (automatic)
+- [ ] Foreign keys (manual, but critical)
+- [ ] Columns in WHERE clauses
+- [ ] Columns in JOIN conditions
+- [ ] Columns in ORDER BY (frequently sorted)
+- [ ] Composite indexes for multi-column queries
+
+### Index Types
+- [ ] B-tree: Default, good for most cases
+- [ ] GIN: JSONB fields, full-text search, arrays
+- [ ] GiST: Geometric data, range types
+- [ ] BRIN: Large tables with natural ordering
+
+### Index Anti-patterns
+- [ ] Don't index low-cardinality columns alone
+- [ ] Don't create redundant indexes
+- [ ] Don't index frequently updated columns without reason
+- [ ] Monitor unused indexes with `pg_stat_user_indexes`
+
+---
+
+## QUERY OPTIMIZATION
+
+### General Rules
+- [ ] Use EXPLAIN ANALYZE before optimizing
+- [ ] Avoid SELECT * in production code
+- [ ] Use specific columns in SELECT
+- [ ] Limit result sets (pagination)
+- [ ] Use EXISTS instead of COUNT for existence checks
+
+### Join Optimization
+- [ ] Ensure foreign keys are indexed
+- [ ] Use appropriate join types (INNER, LEFT, etc.)
+- [ ] Consider query order for optimal execution
+- [ ] Break complex joins into CTEs if clearer
+
+### Subquery vs JOIN
+- [ ] Prefer JOINs for related data retrieval
+- [ ] Use subqueries for scalar values
+- [ ] CTEs for complex, multi-step queries
+- [ ] Avoid correlated subqueries when possible
+
+---
+
+## DATA INTEGRITY
+
+### Constraints
+- [ ] Primary key on every table
+- [ ] Foreign keys with appropriate ON DELETE/UPDATE
+- [ ] NOT NULL where data is required
+- [ ] CHECK constraints for valid value ranges
+- [ ] UNIQUE constraints for business rules
+
+### Referential Actions
+```sql
+-- Safe cascade for dependent data
+ON DELETE CASCADE
+ON UPDATE CASCADE
+
+-- Protect against accidental deletion
+ON DELETE RESTRICT
+
+-- Set to NULL when parent deleted
+ON DELETE SET NULL
+```
+
+---
+
+## MIGRATIONS
+
+### Best Practices
+- [ ] One concern per migration
+- [ ] Always provide rollback (down) migration
+- [ ] Test migrations on copy of production data
+- [ ] Never modify existing migration files
+- [ ] Use transactions for schema changes
+- [ ] Handle data migrations separately from schema
+
+### Safe Operations
+```sql
+-- Add column (safe)
+ALTER TABLE users ADD COLUMN bio TEXT;
+
+-- Add index concurrently (no lock)
+CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
+
+-- Drop with IF EXISTS (idempotent)
+DROP INDEX IF EXISTS idx_old_index;
+```
+
+### Dangerous Operations
+- [ ] Dropping columns with data
+- [ ] Changing column types
+- [ ] Adding NOT NULL without default
+- [ ] Large table migrations without batching
+
+---
+
+## PERFORMANCE MONITORING
+
+### Key Metrics
+- [ ] Query execution time (pg_stat_statements)
+- [ ] Index usage (pg_stat_user_indexes)
+- [ ] Table bloat (pgstattuple)
+- [ ] Connection pool usage
+- [ ] Cache hit ratio
+
+### Tools
+- [ ] EXPLAIN ANALYZE for query plans
+- [ ] pg_stat_statements for query stats
+- [ ] pgBadger for log analysis
+- [ ] Supabase Dashboard for managed instances
+
+---
+
+## BACKUP & RECOVERY
+
+### Backup Strategy
+- [ ] Automated daily backups
+- [ ] Point-in-time recovery enabled
+- [ ] Off-site backup storage
+- [ ] Regular restore testing
+- [ ] Documented recovery procedures
+
+### Supabase Specific
+- [ ] Automatic daily backups (Pro plan+)
+- [ ] Point-in-time recovery available
+- [ ] Download backups via Dashboard
+- [ ] Use `pg_dump` for manual backups
+
+---
+
+## SECURITY
+
+### Access Control
+- [ ] Principle of least privilege
+- [ ] Role-based access (not user-based)
+- [ ] Row Level Security (RLS) for multi-tenant
+- [ ] Never expose superuser credentials
+- [ ] Rotate credentials regularly
+
+### Data Protection
+- [ ] Encrypt sensitive data at rest
+- [ ] Use SSL/TLS for connections
+- [ ] Audit logging for sensitive tables
+- [ ] Mask sensitive data in logs
+
+---
+
+**Reviewer:** ________ **Date:** ________
+**Quality Gate:** [ ] PASS [ ] NEEDS REVIEW

package/.grimoire/product/data/design-token-best-practices.md

@@ -0,0 +1,107 @@
+# Design Token Best Practices
+
+**Source:** Brad's consolidation experience
+**Purpose:** Token naming and organization standards
+
+---
+
+## Naming Conventions
+
+### Semantic > Descriptive
+✅ `color-primary` (semantic - describes purpose)
+❌ `color-blue-500` (descriptive - describes appearance)
+
+**Why:** Semantic names survive redesigns. If primary color changes from blue to purple, `color-primary` still works. `color-blue-500` becomes misleading.
+
+### Use Kebab-Case
+✅ `color-primary-dark`
+❌ `colorPrimaryDark` or `color_primary_dark`
+
+### Variant Suffixes
+- `-light`: Lighter variant, backgrounds, disabled states
+- `-dark`: Darker variant, hover states, active states
+- `-hover`: Explicit hover state
+- `-focus`: Explicit focus state
+
+---
+
+## Token Categories
+
+**Required:**
+- `color` - All color values
+- `spacing` - Padding, margin, gaps
+- `typography` - Fonts, sizes, weights, line-heights
+
+**Recommended:**
+- `radius` - Border radius values
+- `shadow` - Box shadow presets
+- `transition` - Animation timings
+- `z-index` - Stacking order
+
+---
+
+## Token Organization
+
+```yaml
+color:
+  # Primary
+  primary: "#0066CC"
+  primary-dark: "#0052A3"
+  primary-light: "#E6F2FF"
+
+  # Semantic
+  error: "#DC2626"
+  success: "#059669"
+  warning: "#F59E0B"
+
+  # Neutrals
+  neutral-50: "#F9FAFB"
+  neutral-900: "#111827"
+```
+
+---
+
+## Token Values
+
+**Colors:** Hex preferred (`#0066CC`), RGB/HSL acceptable
+**Spacing:** Px units (`16px`), avoid rem in token definition
+**Typography:** Px for sizes, unitless for line-height
+**Timing:** Ms units (`200ms`)
+
+---
+
+## Multi-Format Exports
+
+**Single source of truth:** `tokens.yaml`
+
+**Export to:**
+- `tokens.json` → JavaScript imports
+- `tokens.css` → CSS custom properties
+- `tokens.tailwind.js` → Tailwind theme
+- `tokens.scss` → SCSS variables
+
+**Keep formats in sync:** Regenerate all from tokens.yaml
+
+---
+
+## Token Usage
+
+**Components:**
+```css
+.button {
+  background: var(--color-primary);  /* Use token */
+  padding: var(--space-md);          /* Use token */
+  /* NOT: background: #0066CC; */    /* Hardcoded = bad */
+}
+```
+
+**TypeScript:**
+```typescript
+import { tokens } from '@/tokens';
+const primaryColor = tokens.color.primary;
+```
+
+---
+
+## Brad says:
+"Zero hardcoded values. Tokens or nothing."

package/.grimoire/product/data/elicitation-methods.md

@@ -0,0 +1,135 @@
+# Elicitation Methods Data
+
+## Core Reflective Methods
+
+**Expand or Contract for Audience**
+- Ask whether to 'expand' (add detail, elaborate) or 'contract' (simplify, clarify)
+- Identify specific target audience if relevant
+- Tailor content complexity and depth accordingly
+
+**Explain Reasoning (CoT Step-by-Step)**
+- Walk through the step-by-step thinking process
+- Reveal underlying assumptions and decision points
+- Show how conclusions were reached from current role's perspective
+
+**Critique and Refine**
+- Review output for flaws, inconsistencies, or improvement areas
+- Identify specific weaknesses from role's expertise
+- Suggest refined version reflecting domain knowledge
+
+## Structural Analysis Methods
+
+**Analyze Logical Flow and Dependencies**
+- Examine content structure for logical progression
+- Check internal consistency and coherence
+- Identify and validate dependencies between elements
+- Confirm effective ordering and sequencing
+
+**Assess Alignment with Overall Goals**
+- Evaluate content contribution to stated objectives
+- Identify any misalignments or gaps
+- Interpret alignment from specific role's perspective
+- Suggest adjustments to better serve goals
+
+## Risk and Challenge Methods
+
+**Identify Potential Risks and Unforeseen Issues**
+- Brainstorm potential risks from role's expertise
+- Identify overlooked edge cases or scenarios
+- Anticipate unintended consequences
+- Highlight implementation challenges
+
+**Challenge from Critical Perspective**
+- Adopt critical stance on current content
+- Play devil's advocate from specified viewpoint
+- Argue against proposal highlighting weaknesses
+- Apply YAGNI principles when appropriate (scope trimming)
+
+## Creative Exploration Methods
+
+**Tree of Thoughts Deep Dive**
+- Break problem into discrete "thoughts" or intermediate steps
+- Explore multiple reasoning paths simultaneously
+- Use self-evaluation to classify each path as "sure", "likely", or "impossible"
+- Apply search algorithms (BFS/DFS) to find optimal solution paths
+
+**Hindsight is 20/20: The 'If Only...' Reflection**
+- Imagine retrospective scenario based on current content
+- Identify the one "if only we had known/done X..." insight
+- Describe imagined consequences humorously or dramatically
+- Extract actionable learnings for current context
+
+## Multi-Persona Collaboration Methods
+
+**Agile Team Perspective Shift**
+- Rotate through different Scrum team member viewpoints
+- Product Owner: Focus on user value and business impact
+- Scrum Master: Examine process flow and team dynamics
+- Developer: Assess technical implementation and complexity
+- QA: Identify testing scenarios and quality concerns
+
+**Stakeholder Round Table**
+- Convene virtual meeting with multiple personas
+- Each persona contributes unique perspective on content
+- Identify conflicts and synergies between viewpoints
+- Synthesize insights into actionable recommendations
+
+**Meta-Prompting Analysis**
+- Step back to analyze the structure and logic of current approach
+- Question the format and methodology being used
+- Suggest alternative frameworks or mental models
+- Optimize the elicitation process itself
+
+## Advanced 2025 Techniques
+
+**Self-Consistency Validation**
+- Generate multiple reasoning paths for same problem
+- Compare consistency across different approaches
+- Identify most reliable and robust solution
+- Highlight areas where approaches diverge and why
+
+**ReWOO (Reasoning Without Observation)**
+- Separate parametric reasoning from tool-based actions
+- Create reasoning plan without external dependencies
+- Identify what can be solved through pure reasoning
+- Optimize for efficiency and reduced token usage
+
+**Persona-Pattern Hybrid**
+- Combine specific role expertise with elicitation pattern
+- Architect + Risk Analysis: Deep technical risk assessment
+- UX Expert + User Journey: End-to-end experience critique
+- PM + Stakeholder Analysis: Multi-perspective impact review
+
+**Emergent Collaboration Discovery**
+- Allow multiple perspectives to naturally emerge
+- Identify unexpected insights from persona interactions
+- Explore novel combinations of viewpoints
+- Capture serendipitous discoveries from multi-agent thinking
+
+## Game-Based Elicitation Methods
+
+**Red Team vs Blue Team**
+- Red Team: Attack the proposal, find vulnerabilities
+- Blue Team: Defend and strengthen the approach
+- Competitive analysis reveals blind spots
+- Results in more robust, battle-tested solutions
+
+**Innovation Tournament**
+- Pit multiple alternative approaches against each other
+- Score each approach across different criteria
+- Crowd-source evaluation from different personas
+- Identify winning combination of features
+
+**Escape Room Challenge**
+- Present content as constraints to work within
+- Find creative solutions within tight limitations
+- Identify minimum viable approach
+- Discover innovative workarounds and optimizations
+
+## Process Control
+
+**Proceed / No Further Actions**
+- Acknowledge choice to finalize current work
+- Accept output as-is or move to next step
+- Prepare to continue without additional elicitation
+