grimoire-framework 1.0.0

package/.grimoire/product/checklists/component-quality-checklist.md

@@ -0,0 +1,74 @@
+# Component Quality Checklist
+
+**Purpose:** Validate component before marking complete
+**Agent:** Atlas (Design System Builder)
+**Standard:** Production-ready React/TypeScript components
+
+---
+
+## CODE QUALITY
+
+- [ ] TypeScript (strict) compiles with zero errors
+- [ ] No `any` types used (prefer discriminated unions / utility types)
+- [ ] Props fully typed (VariantProps + component-specific interface)
+- [ ] ForwardRef + displayName implemented when required
+- [ ] TSDoc comments describe props, defaults, accessibility
+- [ ] Component exported as named export (tree-shakeable)
+
+---
+
+## STYLING
+
+- [ ] Tailwind utilities reference semantic tokens (no hardcoded values)
+- [ ] `cva` variant catalogue defined with defaults + compound variants
+- [ ] `cn` (tailwind-merge) handles conditional classes (no conflicts)
+- [ ] Responsive/density variants implemented where required
+- [ ] Dark mode parity confirmed (`data-theme="dark"`)
+
+---
+
+## ACCESSIBILITY (WCAG AA MINIMUM)
+
+- [ ] Semantic HTML elements used (button vs div, etc.)
+- [ ] ARIA attributes present (aria-expanded, aria-busy, aria-live, etc.)
+- [ ] WCAG 2.2 AA & APCA contrast thresholds satisfied (light + dark)
+- [ ] Keyboard navigation works (Tab/Shift+Tab, Enter, Space)
+- [ ] focus-visible styling present with 3:1 contrast
+- [ ] Loading/disabled states handled correctly (aria-busy/aria-disabled)
+- [ ] Screen reader testing (VoiceOver/NVDA) recorded or delegated
+
+---
+
+## TESTING
+
+- [ ] Unit tests written (React Testing Library)
+- [ ] Variants/sizes/compound states tested
+- [ ] Loading + disabled behaviour covered
+- [ ] Event handlers tested (click, keyboard, pointer)
+- [ ] jest-axe (or equivalent) accessibility audit passes
+- [ ] Test coverage ≥85% (statements/functions/branches)
+- [ ] All tests pass locally & in CI
+
+---
+
+## DOCUMENTATION
+
+- [ ] Component.md (or MDX) created
+- [ ] Props + Variant tables documented
+- [ ] Usage examples include light/dark + loading states
+- [ ] Accessibility considerations recorded (ARIA, keyboard)
+- [ ] Migration notes / design rationale captured if applicable
+
+---
+
+## STORYBOOK (if enabled)
+
+- [ ] Stories file created (Storybook 8 CSF)
+- [ ] Story per variant/size + loading/disabled states
+- [ ] Controls/args configured (Docs tab updated)
+- [ ] Visual regression baselines captured (if enabled)
+
+---
+
+**Reviewer:** ________ **Date:** ________
+**Quality Gate:** [ ] PASS [ ] FAIL

package/.grimoire/product/checklists/database-design-checklist.md

@@ -0,0 +1,119 @@
+# Database Design Checklist
+
+## Instructions for Data Engineer Agent
+
+When designing a new database schema or reviewing significant changes, go through each item in this checklist. Report the status of each item (e.g., [x] Done, [ ] Not Done, [N/A] Not Applicable) and provide brief comments if necessary.
+
+[[LLM: INITIALIZATION INSTRUCTIONS - DATABASE DESIGN VALIDATION
+
+This checklist is for DATA ENGINEER AGENTS validating database schema designs.
+
+IMPORTANT: Good database design prevents problems that are expensive to fix later. Take time to verify each item.
+
+EXECUTION APPROACH:
+
+1. Review the complete design before checking items
+2. Mark items as [x] Done, [ ] Not Done, or [N/A] Not Applicable
+3. Add comments explaining design decisions
+4. Flag potential issues or trade-offs
+5. Consider both current and future requirements
+
+Design for correctness first, then optimize.]]
+
+## Checklist Items
+
+1. **Domain Model Alignment:**
+
+   [[LLM: Schema should reflect business requirements]]
+
+   - [ ] All required entities from domain model are represented
+   - [ ] Entity relationships match business logic
+   - [ ] Cardinality (1:1, 1:N, M:N) correctly implemented
+   - [ ] Business rules can be enforced at database level
+   - [ ] Naming conventions are consistent and meaningful
+
+2. **Table Design:**
+
+   [[LLM: Tables are the foundation. Get them right]]
+
+   - [ ] Every table has a primary key (preferably UUID)
+   - [ ] created_at and updated_at timestamps on all tables
+   - [ ] Soft delete (deleted_at) where audit trail needed
+   - [ ] Appropriate data types chosen for each column
+   - [ ] Column names follow snake_case convention
+
+3. **Relationships & Constraints:**
+
+   [[LLM: Constraints protect data integrity]]
+
+   - [ ] Foreign keys defined for all relationships
+   - [ ] ON DELETE behavior specified (CASCADE, SET NULL, RESTRICT)
+   - [ ] Unique constraints on business keys
+   - [ ] CHECK constraints for value validation
+   - [ ] NOT NULL on required fields
+
+4. **Indexing Strategy:**
+
+   [[LLM: Indexes enable performance. Plan them carefully]]
+
+   - [ ] Primary key automatically indexed
+   - [ ] Foreign keys have indexes
+   - [ ] Frequently queried columns indexed
+   - [ ] Composite indexes for common query patterns
+   - [ ] No over-indexing (each index has justification)
+
+5. **Normalization & Denormalization:**
+
+   [[LLM: Balance normalization with practical needs]]
+
+   - [ ] At minimum 3NF (Third Normal Form) achieved
+   - [ ] Denormalization decisions documented with justification
+   - [ ] No data redundancy without explicit reason
+   - [ ] Update anomalies prevented
+   - [ ] Delete anomalies prevented
+
+6. **Security Design:**
+
+   [[LLM: Security must be built in, not bolted on]]
+
+   - [ ] Tables categorized by sensitivity level
+   - [ ] RLS policy strategy defined for each table
+   - [ ] Sensitive columns identified (PII, credentials)
+   - [ ] Audit logging requirements defined
+   - [ ] Access patterns documented
+
+7. **Performance Considerations:**
+
+   [[LLM: Design for expected scale and access patterns]]
+
+   - [ ] Expected data volumes estimated
+   - [ ] Query patterns identified and optimized for
+   - [ ] Partitioning strategy considered (if large tables)
+   - [ ] Archival strategy for old data considered
+   - [ ] Read/write ratio considered
+
+8. **Documentation:**
+
+   [[LLM: Others need to understand your design]]
+
+   - [ ] Entity-Relationship Diagram (ERD) created
+   - [ ] Each table purpose documented
+   - [ ] Complex relationships explained
+   - [ ] Design decisions recorded
+   - [ ] COMMENT ON planned for production schema
+
+## Final Confirmation
+
+[[LLM: FINAL DESIGN REVIEW SUMMARY
+
+After completing the checklist:
+
+1. Summarize the database design
+2. List any items marked as [ ] Not Done with explanations
+3. Document known trade-offs and their rationale
+4. Identify areas that may need future attention
+5. Confirm design is ready for implementation
+
+Good design is the foundation of reliable systems.]]
+
+- [ ] I, the Data Engineer Agent, confirm that this database design has been thoroughly reviewed and is ready for implementation.

package/.grimoire/product/checklists/dba-predeploy-checklist.md

@@ -0,0 +1,97 @@
+# DBA Pre-Deploy Checklist
+
+## Instructions for Data Engineer Agent
+
+Before deploying database changes to production, please go through each item in this checklist. Report the status of each item (e.g., [x] Done, [ ] Not Done, [N/A] Not Applicable) and provide brief comments if necessary.
+
+[[LLM: INITIALIZATION INSTRUCTIONS - DBA PRE-DEPLOY VALIDATION
+
+This checklist is for DATA ENGINEER AGENTS to validate database changes before production deployment.
+
+IMPORTANT: Database changes are often irreversible or costly to fix. This checklist ensures safe deployment.
+
+EXECUTION APPROACH:
+
+1. Go through each section systematically
+2. Mark items as [x] Done, [ ] Not Done, or [N/A] Not Applicable
+3. Add brief comments explaining any [ ] or [N/A] items
+4. Be specific about what was validated
+5. Flag any concerns or risks identified
+
+Production safety is paramount.]]
+
+## Checklist Items
+
+1. **Migration Validation:**
+
+   [[LLM: Migrations must be safe and reversible]]
+
+   - [ ] All migrations have been tested in development environment
+   - [ ] Migrations are idempotent (safe to run multiple times)
+   - [ ] Rollback scripts exist for all schema changes
+   - [ ] Migration order dependencies are documented
+   - [ ] No destructive operations without explicit safeguards
+
+2. **Schema Review:**
+
+   [[LLM: Schema changes can break applications. Verify carefully]]
+
+   - [ ] No breaking changes to existing APIs/tables
+   - [ ] Foreign key constraints are properly defined
+   - [ ] Indexes exist for all foreign keys and frequently queried columns
+   - [ ] NOT NULL constraints are appropriate
+   - [ ] Default values are set where needed
+
+3. **Security Review:**
+
+   [[LLM: Database security is critical. Check each item]]
+
+   - [ ] RLS policies are enabled on all user-facing tables
+   - [ ] RLS policies have been tested with positive and negative cases
+   - [ ] No sensitive data exposed without proper authorization
+   - [ ] SECURITY DEFINER functions are justified and safe
+   - [ ] No hardcoded credentials or secrets in migrations
+
+4. **Performance Review:**
+
+   [[LLM: Performance issues in production are costly. Validate]]
+
+   - [ ] Large table alterations have been planned for low-traffic periods
+   - [ ] New indexes have been tested for query performance
+   - [ ] No full table scans introduced on large tables
+   - [ ] EXPLAIN ANALYZE run on critical queries
+   - [ ] Connection pooling considerations addressed
+
+5. **Backup & Recovery:**
+
+   [[LLM: Always have a way back. Ensure recovery options]]
+
+   - [ ] Database snapshot created before deployment
+   - [ ] Rollback procedure documented and tested
+   - [ ] Recovery time estimate documented
+   - [ ] Data backup verified and accessible
+
+6. **Documentation:**
+
+   [[LLM: Future DBAs need to understand what changed]]
+
+   - [ ] COMMENT ON statements added for new tables/columns
+   - [ ] Migration notes document the purpose of changes
+   - [ ] Breaking changes communicated to development team
+   - [ ] Changelog updated with database changes
+
+## Final Confirmation
+
+[[LLM: FINAL PRE-DEPLOY SUMMARY
+
+After completing the checklist:
+
+1. Summarize database changes being deployed
+2. List any items marked as [ ] Not Done with explanations
+3. Identify risks and mitigation strategies
+4. Confirm rollback procedure is ready
+5. Confirm whether deployment should proceed
+
+Production database changes require confidence.]]
+
+- [ ] I, the Data Engineer Agent, confirm that all applicable items above have been addressed and deployment is safe to proceed.

package/.grimoire/product/checklists/dba-rollback-checklist.md

@@ -0,0 +1,99 @@
+# DBA Rollback Checklist
+
+## Instructions for Data Engineer Agent
+
+When a database rollback is needed, go through each item in this checklist. Report the status of each item (e.g., [x] Done, [ ] Not Done, [N/A] Not Applicable) and provide brief comments if necessary.
+
+[[LLM: INITIALIZATION INSTRUCTIONS - DBA ROLLBACK EXECUTION
+
+This checklist is for DATA ENGINEER AGENTS executing database rollbacks.
+
+IMPORTANT: Rollbacks must be executed carefully to avoid data loss. Follow this checklist precisely.
+
+EXECUTION APPROACH:
+
+1. Remain calm - hasty rollbacks cause more problems
+2. Go through each section in order
+3. Mark items as [x] Done, [ ] Not Done, or [N/A] Not Applicable
+4. Document everything for post-mortem analysis
+5. Communicate status to stakeholders
+
+Controlled rollback is better than panic.]]
+
+## Checklist Items
+
+1. **Situation Assessment:**
+
+   [[LLM: Understand the problem before acting]]
+
+   - [ ] Issue clearly identified and documented
+   - [ ] Impact assessment completed (affected users, data, features)
+   - [ ] Decision to rollback confirmed by appropriate stakeholder
+   - [ ] Current database state captured (snapshot if possible)
+   - [ ] Affected migration(s) identified
+
+2. **Pre-Rollback Preparation:**
+
+   [[LLM: Prepare before executing any rollback]]
+
+   - [ ] Rollback script(s) located and reviewed
+   - [ ] Dependencies between migrations understood
+   - [ ] Application instances notified or stopped (if needed)
+   - [ ] Maintenance mode enabled (if available)
+   - [ ] Team members notified of rollback in progress
+
+3. **Rollback Execution:**
+
+   [[LLM: Execute carefully and monitor]]
+
+   - [ ] Database connection established with appropriate privileges
+   - [ ] Transaction started for rollback operations
+   - [ ] Rollback script executed
+   - [ ] No errors during execution
+   - [ ] Transaction committed (or rolled back if errors)
+
+4. **Post-Rollback Validation:**
+
+   [[LLM: Verify the rollback was successful]]
+
+   - [ ] Schema state matches expected pre-migration state
+   - [ ] Application functionality restored
+   - [ ] No data corruption detected
+   - [ ] RLS policies functioning correctly
+   - [ ] Critical queries performing as expected
+
+5. **Recovery & Communication:**
+
+   [[LLM: Complete the recovery process]]
+
+   - [ ] Application instances restarted (if stopped)
+   - [ ] Maintenance mode disabled
+   - [ ] Stakeholders notified of rollback completion
+   - [ ] End users notified (if necessary)
+   - [ ] Monitoring confirmed normal operations
+
+6. **Documentation & Post-Mortem:**
+
+   [[LLM: Learn from this incident]]
+
+   - [ ] Incident timeline documented
+   - [ ] Root cause identified (if known)
+   - [ ] Rollback procedure effectiveness noted
+   - [ ] Improvements for future rollbacks documented
+   - [ ] Post-mortem meeting scheduled (if significant incident)
+
+## Final Confirmation
+
+[[LLM: FINAL ROLLBACK SUMMARY
+
+After completing the checklist:
+
+1. Summarize what was rolled back and why
+2. Confirm current database state is stable
+3. Document any data impact
+4. Identify follow-up actions needed
+5. Confirm system is operational
+
+Document everything for future reference.]]
+
+- [ ] I, the Data Engineer Agent, confirm that the rollback has been completed successfully and the system is stable.

package/.grimoire/product/checklists/migration-readiness-checklist.md

@@ -0,0 +1,75 @@
+# Migration Readiness Checklist
+
+**Purpose:** Validate system ready for production migration
+**Agent:** Brad (Design System Architect)
+**Phase:** Before migration rollout
+
+---
+
+## FOUNDATION (Phase 1 Ready)
+
+- [ ] Tokens generated (core/semantic/component) and validated
+- [ ] DTCG export created + validator passes
+- [ ] Token coverage >95% with dark mode parity recorded
+- [ ] Tailwind v4 (`@theme`, Oxide benchmarks) configured
+- [ ] Build pipeline configured (CI + lint + visual regression)
+- [ ] No visual regressions in test environment
+
+---
+
+## COMPONENTS (Phase 2 Ready)
+
+- [ ] High-impact components built (Button, Input, Card minimum)
+- [ ] Components adhere to Tailwind+cva patterns, pass quality checklist
+- [ ] Component tests passing (≥85% coverage + jest-axe)
+- [ ] Documentation + Storybook 8 (if using) updated
+- [ ] Shadcn/Radix library bootstrap completed (if adopted)
+
+---
+
+## MIGRATION PLAN
+
+- [ ] 4-phase migration strategy documented
+- [ ] Component mapping created (old → new)
+- [ ] Rollback procedures defined
+- [ ] Timeline realistic for team velocity
+- [ ] Stakeholder approval obtained
+- [ ] Tailwind upgrade + token rollout sequencing communicated
+
+---
+
+## TEAM READINESS
+
+- [ ] Team trained on design system usage
+- [ ] Tailwind v4 + Shadcn guidelines shared (.cursorrules updated)
+- [ ] Migration guide distributed
+- [ ] Support channel established
+- [ ] Code review process updated
+
+---
+
+## RISK MITIGATION
+
+- [ ] Backups created
+- [ ] Feature flags enabled (if using)
+- [ ] Monitoring in place
+- [ ] Rollback tested
+- [ ] Emergency contacts defined
+
+---
+
+## METRICS TRACKING
+
+- [ ] Baseline metrics captured
+- [ ] ROI tracking dashboard ready
+- [ ] Pattern usage monitoring enabled
+- [ ] Velocity metrics defined
+- [ ] Oxide build metrics + CSS bundle size monitored (CI dashboards)
+
+---
+
+**Go/No-Go Decision:**
+[ ] GO - All critical items checked
+[ ] NO-GO - Blockers:_________________
+
+**Approved By:** ________ **Date:** ________

package/.grimoire/product/checklists/pattern-audit-checklist.md

@@ -0,0 +1,88 @@
+# Pattern Audit Checklist
+
+**Purpose:** Validate audit results before consolidation
+**Agent:** Brad (Design System Architect)
+**References:** audit-codebase.md task
+
+---
+
+## SCAN COMPLETENESS
+
+- [ ] All UI file types detected (React, Vue, HTML, CSS)
+- [ ] Scan completed without critical errors
+- [ ] Total file count matches expectations
+- [ ] No permission errors blocking scan
+
+---
+
+## PATTERN DETECTION
+
+### Buttons
+- [ ] Button instances counted accurately
+- [ ] Unique button patterns identified
+- [ ] Redundancy factor calculated (instances / unique)
+- [ ] Most-used buttons captured
+
+### Colors
+- [ ] Hex colors extracted (#RGB, #RRGGBB)
+- [ ] RGB/RGBA colors extracted
+- [ ] Total unique colors counted
+- [ ] Top 10 most-used colors identified
+- [ ] Redundancy factor calculated
+
+### Spacing
+- [ ] Padding values extracted
+- [ ] Margin values extracted
+- [ ] Unique spacing values counted
+
+### Typography
+- [ ] Font families identified
+- [ ] Font sizes extracted
+- [ ] Font weights counted
+
+### Forms
+- [ ] Input elements counted
+- [ ] Form elements counted
+- [ ] Unique patterns identified
+
+---
+
+## OUTPUT VALIDATION
+
+- [ ] pattern-inventory.json generated
+- [ ] JSON is valid and parseable
+- [ ] All pattern types included
+- [ ] Metadata complete (timestamp, scan path, file counts)
+- [ ] .state.yaml created
+- [ ] State file has valid YAML syntax
+- [ ] Phase set to "audit_complete"
+- [ ] Tailwind version/config path captured (if applicable)
+
+---
+
+## METRICS VALIDATION
+
+- [ ] Redundancy factors >1 (indicates duplication)
+- [ ] Pattern counts seem reasonable (not artificially inflated)
+- [ ] No zero counts for major pattern types (unless truly zero)
+
+---
+
+## NEXT STEPS DECISION
+
+**If redundancy factors >3x:**
+- ✅ Proceed to *consolidate
+- Significant pattern reduction opportunity
+
+**If redundancy factors <2x:**
+- ⚠️ Codebase is relatively clean
+- Consider if design system is worth investment
+
+**If colors >50 or buttons >20:**
+- 🚨 Major technical debt
+- Strong candidate for consolidation
+
+---
+
+**Reviewer:** ________ **Date:** ________
+**Audit Quality:** [ ] Excellent [ ] Good [ ] Needs Review