Matrix Pattern MCP Server

# Matrix Pattern System - Claude Instructions ## 🎯 Core Principle: "Every Change Has a Specification" Welcome! This project uses the Matrix Pattern System for specification-driven development. The matrix pattern helps you maintain a clear specification layer for ALL development work while giving you complete freedom to implement solutions. **Key Philosophy**: Specify in the Matrix, Implement in the Code ## 📋 Quick Start Guide ### Your Workflow for ANY Task: 1. **Before coding**: Create/update a matrix vertical (2-3 minutes) 2. **During coding**: Implement freely with all tools available 3. **After coding**: Update build logs in the matrix (1-2 minutes) ### Essential Commands: ```bash # Start any work by creating a vertical matrix_create_cell --vertical "feature_name_2024" --horizontal "specs" --content "# What I'm building" # Check what you're working on matrix_list_verticals # See what's missing in your vertical matrix_sync_vertical --vertical "feature_name_2024" ``` ## 🔄 Development Workflow ### For ANY Development Task (Features, Bugs, Refactoring, Experiments): #### 1. Specification Phase (Matrix Pattern - 5 minutes) ```bash # Example: Fixing an authentication bug matrix_create_cell --vertical "fix_auth_timeout_2024_01" --horizontal "specs" \ --content "# Fix: Session timeout not refreshing ## Problem Users are being logged out despite activity ## Solution Refresh token on API calls" matrix_create_cell --vertical "fix_auth_timeout_2024_01" --horizontal "tests" \ --content "# Test Scenarios - Token refresh on API call - Multiple concurrent requests - Timeout boundary conditions" # Mark non-applicable horizontals as empty matrix_create_cell --vertical "fix_auth_timeout_2024_01" --horizontal "design" \ --isEmpty true --emptyReason "No UI changes required" ``` #### 2. Implementation Phase (Normal Development - Use Any Tools) ```bash # Now implement freely! # Edit any files vim src/auth/session-manager.js vim src/middleware/auth.js # Run tests npm test # Use git normally git add -A git commit -m "fix: Refresh auth token on API calls" # Create new files if needed touch src/utils/token-refresh.js # Run any commands npm run build docker-compose up ``` #### 3. Documentation Phase (Matrix Pattern - 2 minutes) ```bash # Document what you implemented matrix_create_cell --vertical "fix_auth_timeout_2024_01" --horizontal "backend_build_logs" \ --content "# Implementation Complete ## Files Modified - src/auth/session-manager.js:45 - Added refresh logic - src/middleware/auth.js:120 - Token check before expiry ## Tests Added - test/auth/token-refresh.test.js Resolved in PR #234" ``` ## 🎯 Quick Decision Tree ```mermaid graph TD A[Starting Any Work?] --> B{Does vertical exist?} B -->|No| C[Create vertical with specs] B -->|Yes| D[Continue with that vertical] C --> E[Implement freely] D --> E E --> F[Update build_logs when done] F --> G{All horizontals complete?} G -->|Yes| H[Run vertical sync] G -->|No| I[Mark empty or defer] ``` ## 📊 When to Use Each Horizontal ### Always Required (Minimum): - **specs** - ALWAYS: Even one line describing what you're doing - **tests** - ALWAYS: At least describe what should be tested ### Usually Required: - **api** - If ANY endpoints change (internal or external) - **schema** - If ANY data structures change - **backend/frontend** - If implementing in that layer ### Sometimes Required: - **design** - Only for UI/UX changes - **screens** - Only for new views/pages - **gateways** - Only for external service integrations - **mockups** - Only for visual prototypes ### Mark as Empty When Not Applicable: ```bash # Example: Backend fix doesn't need frontend changes matrix_create_cell --vertical "backend_optimization" --horizontal "frontend" \ --isEmpty true --emptyReason "Backend only optimization" ``` ## 💡 Real-World Examples ### Example 1: Quick Bug Fix (Total: 10 minutes) ```bash # 1. Spec it (2 min) matrix_create_cell --vertical "fix_null_user_2024_01" --horizontal "specs" \ --content "# Fix: Handle null user in profile service Users with deleted accounts causing crashes" matrix_create_cell --vertical "fix_null_user_2024_01" --horizontal "tests" \ --content "# Tests: Null user handling - getUserProfile with null ID - getUserProfile with deleted user" # 2. Fix it (6 min) - Use normal development tools echo "Implementing fix..." # Edit files, run tests, commit changes # 3. Log it (2 min) matrix_create_cell --vertical "fix_null_user_2024_01" --horizontal "backend_build_logs" \ --content "# Fixed: Added null checks - src/services/profile.js:89 - Added guards for deleted users" ``` ### Example 2: New Feature (Total: 2 hours) ```bash # 1. Full specification (10 min) matrix_create_cell --vertical "user_notifications_v1" --horizontal "specs" \ --content "# Feature: User Notification System ## Requirements - Email notifications - In-app notifications - User preferences" matrix_create_cell --vertical "user_notifications_v1" --horizontal "api" \ --content "# API Endpoints POST /api/notifications/send GET /api/notifications/user/:id PUT /api/notifications/preferences" matrix_create_cell --vertical "user_notifications_v1" --horizontal "schema" \ --content "# Database Schema notifications table: - id, user_id, type, content, read, created_at user_preferences table: - user_id, email_enabled, push_enabled" # 2. Implementation (1h 45min) - Full freedom to code # 3. Documentation (5 min) matrix_create_cell --vertical "user_notifications_v1" --horizontal "backend_build_logs" \ --content "# Implementation complete - Services in src/notifications/ - Tests in test/notifications/ - Migration in migrations/001_notifications.sql" ``` ### Example 3: Refactoring (Total: 45 minutes) ```bash # 1. Plan the refactor (5 min) matrix_create_cell --vertical "refactor_payment_2024_01" --horizontal "specs" \ --content "# Refactor: Extract Payment Provider Interface ## Goals - Decouple from Stripe - Support multiple providers - Maintain backward compatibility" # 2. Implement refactor (35 min) - Use all your tools # 3. Document changes (5 min) matrix_create_cell --vertical "refactor_payment_2024_01" --horizontal "backend_build_logs" \ --content "# Refactoring Complete ## New Structure - src/payments/interface.js - Abstract interface - src/payments/providers/stripe.js - src/payments/providers/paypal.js All tests passing, no API changes" ``` ## 🔍 Checking State & Recovery ### Understanding Your Current State ```bash # What am I working on? matrix_list_verticals # What's incomplete in my current work? matrix_sync_vertical --vertical "current_feature" # How has the API evolved? matrix_sync_horizontal --horizontal "api" # What's the status of all tests? matrix_sync_horizontal --horizontal "tests" ``` ### Recovery Scenarios #### "I forgot to create a spec before coding" ```bash # It's OK! Create it now retrospectively matrix_create_cell --vertical "feature_x" --horizontal "specs" \ --content "# Retrospective Spec Already implemented: [describe what you did]" ``` #### "I'm not sure what vertical to use" ```bash # List existing ones first matrix_list_verticals # Create descriptive names with dates # Pattern: action_target_date # Examples: fix_auth_2024_01, feature_search_v2, refactor_db_2024_02 ``` #### "This is just a one-line change" ```bash # Still create a minimal vertical (30 seconds) matrix_create_cell --vertical "fix_typo_header_2024_01" --horizontal "specs" \ --content "Fix typo in header" # Implementation... matrix_create_cell --vertical "fix_typo_header_2024_01" --horizontal "frontend_build_logs" \ --content "Fixed in components/Header.jsx:12" ``` #### "I'm experimenting and not sure what I'll build" ```bash # Create an experiment vertical matrix_create_cell --vertical "experiment_ml_integration_2024_01" --horizontal "specs" \ --content "# Experiment: ML Integration ## Testing - Feasibility of TensorFlow.js - Performance implications - API design options" # Update as you learn more ``` ## 🛠️ Matrix Pattern Tools Reference ### Core Tools (Use These Daily) #### 1. matrix_create_cell Create or update a cell in the matrix ```bash matrix_create_cell \ --vertical "<feature/fix/refactor>_<name>_<date>" \ --horizontal "<type>" \ --content "<markdown content>" # Mark as empty when not applicable matrix_create_cell \ --vertical "backend_fix" \ --horizontal "frontend" \ --isEmpty true \ --emptyReason "Backend only change" ``` #### 2. matrix_read_cell Read existing specifications ```bash matrix_read_cell --vertical "feature_x" --horizontal "api" ``` #### 3. matrix_list_verticals See all your work streams ```bash matrix_list_verticals ``` #### 4. matrix_list_horizontals See all available horizontal types ```bash matrix_list_horizontals ``` #### 5. matrix_sync_vertical Check completeness of a vertical ```bash matrix_sync_vertical --vertical "feature_x" ``` #### 6. matrix_sync_horizontal See evolution across verticals ```bash matrix_sync_horizontal --horizontal "api" ``` #### 7. matrix_read_horizontal_instructions Get guidance for a horizontal type ```bash matrix_read_horizontal_instructions --horizontal "schema" ``` ## 🔗 Integration with Development Tools ### Git Integration Include vertical references in commits: ```bash git commit -m "feat: Add user notifications [matrix:user_notifications_v1]" git commit -m "fix: Auth timeout issue [matrix:fix_auth_timeout_2024_01]" ``` ### Pull Request Templates ```markdown ## Changes Implementation of `user_notifications_v1` vertical ## Matrix Pattern Reference - **Vertical**: `user_notifications_v1` - **Completeness**: 8/10 horizontals - **Specs**: ✅ Complete - **Tests**: ✅ Complete - **API**: ✅ Complete - **Build Logs**: ✅ Complete ## Related Matrix Sync Run `matrix_sync_vertical --vertical "user_notifications_v1"` for full status ``` ### Issue Tracking Link issues to verticals: ```markdown GitHub Issue #123 → Vertical: `fix_issue_123` JIRA PROJ-456 → Vertical: `feature_proj_456` ``` ## ✅ Best Practices ### DO: ✅ Create vertical BEFORE starting any work (even tiny fixes) ✅ Use descriptive vertical names: `action_target_date` ✅ Fill specs horizontal first (clarifies thinking) ✅ Mark horizontals empty when truly not applicable ✅ Reference specific code locations in build_logs ✅ Keep cells concise but complete (aim for clarity) ✅ Run sync after completing work ✅ Use matrix for specifications, use files for code ### DON'T: ❌ Skip specs because "it's just a small change" ❌ Try to modify existing cells (forward-only!) ❌ Create verticals after implementation ❌ Leave verticals incomplete without empty markers ❌ Store actual code in matrix cells ❌ Overthink - when in doubt, create a simple spec ❌ Let the matrix slow you down - it should help, not hinder ## 🚀 Advanced Patterns ### Linking Related Verticals When work spans multiple verticals: ```bash matrix_create_cell --vertical "refactor_auth_phase1_2024_01" --horizontal "specs" \ --content "# Phase 1 of Auth Refactor Related verticals: - refactor_auth_phase2_2024_01 - refactor_auth_phase3_2024_01 This phase: Extract authentication service" ``` ### Tracking Technical Debt ```bash matrix_create_cell --vertical "tech_debt_q1_2024" --horizontal "specs" \ --content "# Q1 Technical Debt Items ## Identified Issues 1. Payment service needs refactoring → vertical: refactor_payment_2024_02 2. Test coverage below 80% → vertical: improve_test_coverage_2024_02 3. API versioning needed → vertical: api_versioning_v1" ``` ### Sprint Planning with Matrix ```bash # Create sprint vertical matrix_create_cell --vertical "sprint_23_2024_01" --horizontal "specs" \ --content "# Sprint 23 Goals ## Planned Verticals - feature_user_search_v1 - fix_performance_issues_2024_01 - refactor_cache_layer_2024_01" ``` ## 🆘 Troubleshooting ### Common Issues & Solutions #### "The matrix feels like overhead" - Keep specs minimal - even 2-3 lines is fine - Use empty markers liberally - Focus on value: specs help you think clearly #### "I keep forgetting to create verticals" - Make it a habit: Open terminal → Create vertical → Start coding - Use shell aliases for common patterns - Set up git hooks to remind you #### "Too many verticals to track" - Use naming patterns consistently - Archive completed work periodically - Focus on active verticals only #### "Unsure about horizontal applicability" - When in doubt, mark as empty with reason - Read horizontal instructions for guidance - Start with just specs and tests, add others as needed ## 📚 Horizontal-Specific Guidelines ### {{HORIZONTALS_SECTION}} <!-- This section will be dynamically populated based on selected horizontals --> ## 🎓 Learning Resources ### Matrix Pattern Principles 1. **Forward-Only Constraint**: Once written, cells are immutable (like git commits) 2. **Completeness**: Every vertical should address all applicable horizontals 3. **Evolution Tracking**: Horizontals show how concepts evolve across verticals 4. **Specification-First**: Think before you code, specify before you implement ### Getting Help - Run `matrix_read_horizontal_instructions --horizontal "<type>"` for horizontal guidance - Check sync reports for patterns: `matrix_sync_horizontal --horizontal "api"` - Review existing verticals for examples: `matrix_list_verticals` ## 🎯 Remember The Matrix Pattern is here to **help** you, not restrict you: - It provides clarity and traceability - It encourages thinking before coding - It documents your decision-making process - It enables team coordination - It maintains project history **You have complete freedom to implement however you want** - the matrix just ensures your work is well-specified and documented. --- *Generated by Matrix Pattern System v1.0.0* *Project initialized: {{INIT_DATE}}* *Selected horizontals: {{SELECTED_HORIZONTALS}}*