start-vibing 1.1.3 → 1.1.4

package/template/.claude/config/project-config.json

@@ -2,12 +2,6 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$comment": "Project-specific configuration. Agents read this to adapt to your project.",
 
-  "project": {
-    "name": "my-project",
-    "description": "Project description here",
-    "type": "monorepo"
-  },
-
   "stack": {
     "runtime": "bun",
     "language": "typescript",
@@ -29,7 +23,10 @@
   "pathAliases": {
     "$types/*": "./types/*",
     "@common/*": "./common/*",
-    "@common": "./common/index.ts"
+    "@common": "./common/index.ts",
+    "@db/*": "./common/db/*",
+    "@db": "./common/db/index.ts",
+    "@apps/*": "./apps/*"
   },
 
   "commands": {

package/template/.claude/hooks/user-prompt-submit.py

@@ -1,68 +1,415 @@
 #!/usr/bin/env python3
 """
-UserPromptSubmit Hook - Lightweight workflow guidance.
-Provides brief context to Claude without verbose output.
+UserPromptSubmit Hook - STRICT Workflow Enforcement
+
+This hook runs BEFORE Claude processes any user prompt and ENFORCES:
+1. MANDATORY detailed todo list creation from prompt
+2. MANDATORY research agent for new features
+3. STRICT workflow: audit -> branch -> implement -> document -> quality -> PR
+4. Separate UI for mobile/tablet/desktop (NOT just responsive)
+5. NRY patterns (Never Repeat Yourself - common Claude mistakes)
+
+Output is sent to Claude as context before processing the user's request.
+
+Based on official Claude Code documentation:
+https://code.claude.com/docs/en/hooks.md
 """
 
 import json
 import sys
+import os
+import re
+from pathlib import Path
+
+PROJECT_DIR = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+WORKFLOW_STATE_PATH = Path(PROJECT_DIR) / '.claude' / 'workflow-state.json'
+SETTINGS_PATH = Path(PROJECT_DIR) / '.claude' / 'settings.json'
+
+# STRICT WORKFLOW SEQUENCE (MANDATORY)
+STRICT_WORKFLOW = """
+┌─────────────────────────────────────────────────────────────────┐
+│                    STRICT WORKFLOW (MANDATORY)                  │
+├─────────────────────────────────────────────────────────────────┤
+│ 1. TODO LIST    → Create DETAILED todo list from prompt        │
+│ 2. RESEARCH     → Run research agent for NEW features          │
+│ 3. AUDIT        → Check last audit docs OR run fresh audit     │
+│ 4. BRANCH       → Create feature/ | fix/ | refactor/ | test/   │
+│ 5. IMPLEMENT    → Follow rules + analyzer approval             │
+│ 6. DOCUMENT     → Document results, bugs, solutions (with hash)│
+│ 7. QUALITY      → typecheck + lint + test (Husky enforced)     │
+│ 8. PR           → Create PR to main with doc references        │
+└─────────────────────────────────────────────────────────────────┘
+"""
+
+# Agent definitions with triggers
+AGENTS = {
+    'orchestrator': {
+        'description': 'Coordinates entire development flow',
+        'triggers': ['implement feature', 'build', 'create', 'fix and test', 'full workflow', 'multi-step'],
+        'priority': 1,
+        'when': 'Task requires >2 agents or touches >3 files'
+    },
+    'analyzer': {
+        'description': 'Analyzes impact before code modification',
+        'triggers': ['implement', 'add feature', 'fix bug', 'refactor', 'change', 'modify', 'update code'],
+        'priority': 2,
+        'when': 'BEFORE any Edit/Write to source files'
+    },
+    'research': {
+        'description': 'Researches best practices (2024-2025) - MANDATORY for new features',
+        'triggers': ['research', 'investigate', 'study', 'best practice', 'how to', 'pattern', 'new feature', 'implement'],
+        'priority': 3,
+        'when': 'MANDATORY for ANY new feature or complex bug fix',
+        'mandatory_for': ['feature', 'fix']
+    },
+    'ui-ux-reviewer': {
+        'description': 'Reviews UI/UX - ENFORCES separate mobile/tablet/desktop UIs',
+        'triggers': ['ui', 'component', 'page', 'design', 'layout', 'style', 'frontend', 'mobile', 'desktop'],
+        'priority': 3,
+        'when': 'Files in components/, app/, or .tsx with JSX',
+        'enforces': 'SEPARATE UIs for each platform (NOT just responsive)'
+    },
+    'documenter': {
+        'description': 'Documents results with commit hash references',
+        'triggers': ['document', 'readme', 'docs', 'explain'],
+        'priority': 4,
+        'when': 'After implementation - MUST include commit hash for audit trail'
+    },
+    'tester': {
+        'description': 'Creates unit tests (Vitest) and E2E tests (Playwright)',
+        'triggers': ['test', 'coverage', 'spec', 'e2e'],
+        'priority': 5,
+        'when': 'After any code implementation'
+    },
+    'security-auditor': {
+        'description': 'Audits security (CAN VETO)',
+        'triggers': ['auth', 'session', 'password', 'token', 'api', 'database', 'user data', 'security'],
+        'priority': 6,
+        'when': 'Code touches auth/, api/, server/, or sensitive data',
+        'can_veto': True
+    },
+    'quality-checker': {
+        'description': 'Runs typecheck, lint, test, build (Husky pre-commit)',
+        'triggers': ['check', 'verify', 'validate', 'run tests', 'quality'],
+        'priority': 7,
+        'when': 'BEFORE any commit - Husky enforces this'
+    },
+    'final-validator': {
+        'description': 'Final validation before commit (CAN VETO)',
+        'triggers': ['final', 'commit ready', 'approve'],
+        'priority': 8,
+        'when': 'Before any commit operation',
+        'can_veto': True
+    },
+    'commit-manager': {
+        'description': 'Creates conventional commits and completes workflow',
+        'triggers': ['commit', 'save changes', 'push', 'finalize', 'git'],
+        'priority': 10,
+        'when': 'FINAL step - after domain-updater, runs complete-task'
+    },
+    'domain-updater': {
+        'description': 'Updates domain knowledge with session learnings',
+        'triggers': ['update domain', 'document learnings', 'session end'],
+        'priority': 9,
+        'when': 'BEFORE commit-manager - updates domains so git stays clean'
+    }
+}
+
+# Workflow sequences (research after analyzer, domain-updater BEFORE commit-manager for clean git)
+WORKFLOWS = {
+    'feature': ['analyzer', 'research', 'ui-ux-reviewer', 'documenter', 'tester', 'security-auditor', 'quality-checker', 'final-validator', 'domain-updater', 'commit-manager'],
+    'fix': ['analyzer', 'research', 'tester', 'security-auditor', 'quality-checker', 'final-validator', 'domain-updater', 'commit-manager'],
+    'refactor': ['analyzer', 'tester', 'quality-checker', 'final-validator', 'domain-updater', 'commit-manager'],
+    'config': ['quality-checker', 'domain-updater', 'commit-manager']
+}
+
+
+def load_workflow_state():
+    """Load current workflow state"""
+    if not WORKFLOW_STATE_PATH.exists():
+        return None
+    try:
+        with open(WORKFLOW_STATE_PATH) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return None
+
 
 def detect_task_type(prompt: str) -> str:
-    """Detect task type from prompt."""
-    p = prompt.lower()
-    if any(w in p for w in ['bug', 'fix', 'error', 'broken', 'issue']):
+    """Detect task type from prompt"""
+    prompt_lower = prompt.lower()
+
+    if any(word in prompt_lower for word in ['bug', 'fix', 'error', 'broken', 'not working', 'issue']):
         return 'fix'
-    if any(w in p for w in ['refactor', 'restructure', 'clean up']):
+    elif any(word in prompt_lower for word in ['refactor', 'restructure', 'reorganize', 'clean up']):
         return 'refactor'
-    if any(w in p for w in ['config', 'setting', '.env', 'package.json']):
+    elif any(word in prompt_lower for word in ['config', 'setting', 'env', 'package.json', 'tsconfig']):
         return 'config'
-    return 'feature'
-
-def get_workflow(task_type: str) -> list:
-    """Get workflow for task type."""
-    workflows = {
-        'feature': ['commit-manager:branch', 'analyzer', 'research', 'implement', 'tester', 'quality-checker', 'domain-updater', 'commit-manager:commit'],
-        'fix': ['commit-manager:branch', 'analyzer', 'implement', 'tester', 'quality-checker', 'domain-updater', 'commit-manager:commit'],
-        'refactor': ['commit-manager:branch', 'analyzer', 'implement', 'tester', 'quality-checker', 'domain-updater', 'commit-manager:commit'],
-        'config': ['quality-checker', 'commit-manager:commit']
-    }
-    return workflows.get(task_type, workflows['feature'])
+    else:
+        return 'feature'
+
+
+def detect_best_agent(prompt: str) -> tuple[str, str]:
+    """Detect best agent for the task"""
+    prompt_lower = prompt.lower()
+
+    # Check for multi-step tasks first
+    multi_step_indicators = ['and then', 'after that', 'also', 'implement', 'build', 'create feature']
+    if any(indicator in prompt_lower for indicator in multi_step_indicators):
+        return 'orchestrator', 'Multi-step task detected - orchestrator will coordinate all agents'
+
+    # Check each agent's triggers
+    matches = []
+    for agent_name, agent_info in AGENTS.items():
+        for trigger in agent_info['triggers']:
+            if trigger in prompt_lower:
+                matches.append((agent_name, agent_info['priority'], trigger))
+
+    if matches:
+        # Sort by priority (lower is better)
+        matches.sort(key=lambda x: x[1])
+        best = matches[0]
+        return best[0], f"Matched trigger '{best[2]}'"
+
+    # Default to orchestrator for unknown tasks
+    return 'orchestrator', 'No specific trigger matched - orchestrator will analyze'
+
+
+def format_agent_list() -> str:
+    """Format agent list for display"""
+    lines = []
+    for name, info in sorted(AGENTS.items(), key=lambda x: x[1]['priority']):
+        veto = ' [CAN VETO]' if info.get('can_veto') else ''
+        lines.append(f"  - {name}: {info['description']}{veto}")
+    return '\n'.join(lines)
+
+
+def format_workflow_status(state: dict) -> str:
+    """Format current workflow status"""
+    if not state or not state.get('currentTask'):
+        return "STATUS: No active task. Start with orchestrator agent"
+
+    task = state['currentTask']
+    agents = task.get('agents', {})
+
+    executed = [name for name, status in agents.items() if status.get('executed')]
+    pending = [name for name, status in agents.items() if not status.get('executed')]
+
+    return f"""STATUS: Task active
+  ID: {task.get('id', 'unknown')}
+  Type: {task.get('type', 'unknown')}
+  Description: {task.get('description', 'unknown')}
+  Executed: {', '.join(executed) if executed else 'none'}
+  Pending: {', '.join(pending) if pending else 'none'}
+  Approved files: {len(task.get('approvedFiles', []))}"""
+
 
 def main():
+    # Read hook input from stdin
     try:
         hook_input = json.load(sys.stdin)
     except json.JSONDecodeError:
-        sys.exit(0)
+        hook_input = {}
+
+    # Get user prompt (may not be available in all hook contexts)
+    prompt = hook_input.get('user_prompt', hook_input.get('prompt', ''))
+
+    # Load current state
+    state = load_workflow_state()
+
+    # Detect task type and best agent
+    task_type = detect_task_type(prompt) if prompt else 'unknown'
+    best_agent, reason = detect_best_agent(prompt) if prompt else ('orchestrator', 'Default')
 
-    prompt = hook_input.get('prompt', '')
-    if not prompt:
-        sys.exit(0)
+    # Check if task is new feature (requires research)
+    is_new_feature = task_type in ['feature'] or any(word in prompt.lower() for word in ['new', 'implement', 'create', 'add'])
+    is_ui_task = any(word in prompt.lower() for word in ['ui', 'component', 'page', 'design', 'layout', 'mobile', 'desktop', 'tablet'])
 
-    task_type = detect_task_type(prompt)
-    workflow = get_workflow(task_type)
+    # Build output message
+    output = f"""
+================================================================================
+STRICT WORKFLOW ENFORCEMENT - UserPromptSubmit Hook
+================================================================================
+{STRICT_WORKFLOW}
 
-    # Compact context for Claude
-    context = f"""Task: {task_type}
-Workflow: {' → '.join(workflow)}
+{"⚠️  NEW FEATURE DETECTED - RESEARCH AGENT IS MANDATORY!" if is_new_feature else ""}
+{"⚠️  UI TASK DETECTED - SEPARATE UIs FOR MOBILE/TABLET/DESKTOP REQUIRED!" if is_ui_task else ""}
 
-Rules:
-- START: commit-manager creates feature branch
-- IMPLEMENT: follow workflow sequence
-- UPDATE: domain-updater before commit
-- END: commit-manager commits and merges to main
+================================================================================
+STEP 1: CREATE DETAILED TODO LIST (MANDATORY)
+================================================================================
 
-Agents: analyzer, research, tester, quality-checker, security-auditor, documenter, ui-ux-reviewer, domain-updater, commit-manager"""
+BEFORE doing anything, you MUST use TodoWrite to create a detailed todo list.
+Break down the user's prompt into specific, actionable items.
 
+Example:
+  User prompt: "Add login feature"
+  Todo list:
+    1. Research login best practices 2024-2025
+    2. Check existing auth documentation
+    3. Create feature/login branch
+    4. Implement login form (mobile UI)
+    5. Implement login form (tablet UI)
+    6. Implement login form (desktop UI)
+    7. Add validation with visual feedback
+    8. Create unit tests
+    9. Create E2E tests
+    10. Document implementation with commit hash
+    11. Run quality gates
+    12. Create PR to main
+
+================================================================================
+AVAILABLE AGENTS:
+{format_agent_list()}
+
+TASK ANALYSIS:
+  Detected type: {task_type}
+  Recommended agent: {best_agent}
+  Reason: {reason}
+  Research required: {"YES (MANDATORY)" if is_new_feature else "Optional"}
+  Separate UIs required: {"YES (MANDATORY)" if is_ui_task else "N/A"}
+  Workflow sequence: {' -> '.join(WORKFLOWS.get(task_type, WORKFLOWS['feature']))}
+
+{format_workflow_status(state)}
+
+================================================================================
+UI ARCHITECTURE RULES (MANDATORY FOR WEB APPS)
+================================================================================
+
+❌ DO NOT make "responsive" UI only
+✅ CREATE SEPARATE UIs for each platform:
+
+MOBILE (375px):
+  - Bottom navigation bar
+  - Full-screen modal for search (closable)
+  - Pull-to-refresh
+  - Touch targets 44x44px minimum
+
+TABLET (768px):
+  - Condensed data in dropdowns
+  - Hybrid collapsible sidebar
+  - Adapted touch/click
+
+DESKTOP (1280px+):
+  - Left sidebar: notifications, profile, nav
+  - Top navbar: centered Levenshtein search
+  - High information density
+
+SHARED:
+  - Featured carousel section
+  - Hidden scrollbars (but scroll works)
+  - Scroll indicators (arrows)
+  - Framer Motion transitions
+
+================================================================================
+INPUT VALIDATION RULES (ALL INPUTS)
+================================================================================
+
+Every input MUST have:
+  - Real-time visual feedback (green/red borders)
+  - Error checklist below input (disappears when fixed)
+  - Autofill validation (prevent email in nickname field)
+  - onInput + onAnimationStart for autofill detection
+
+================================================================================
+NRY - NEVER REPEAT YOURSELF (Common Claude Mistakes)
+================================================================================
+
+❌ Multi-line bash with backslash (breaks permissions)
+❌ Relative paths in permissions
+❌ Ignoring context size (use /compact)
+❌ Relying on undo for critical code
+❌ Executing agent logic manually
+❌ Using bash for file operations (cat, echo >)
+
+✅ Single-line commands with &&
+✅ Absolute paths in permissions
+✅ Commit to git before major changes
+✅ Use Task tool to invoke agents
+✅ Use Read/Write/Edit for files
+
+================================================================================
+AGENT INVOCATION (VIA TASK TOOL ONLY)
+================================================================================
+
+You MUST use the Task tool with subagent_type to invoke agents.
+DO NOT execute agent logic manually - INVOKE the agent properly.
+
+AGENTS INVOCABLE VIA TASK TOOL:
+  - research: Task(subagent_type="research", prompt="...") {"<-- MANDATORY FOR THIS TASK" if is_new_feature else ""}
+  - analyzer: Task(subagent_type="analyzer", prompt="...")
+  - ui-ux-reviewer: Task(subagent_type="ui-ux-reviewer", prompt="...") {"<-- MANDATORY FOR THIS TASK" if is_ui_task else ""}
+  - tester: Task(subagent_type="tester", prompt="...")
+  - security-auditor: Task(subagent_type="security-auditor", prompt="...")
+  - quality-checker: Task(subagent_type="quality-checker", prompt="...")
+  - final-validator: Task(subagent_type="final-validator", prompt="...")
+  - documenter: Task(subagent_type="documenter", prompt="...")
+  - commit-manager: Task(subagent_type="commit-manager", prompt="...")
+  - orchestrator: Task(subagent_type="orchestrator", prompt="...")
+
+================================================================================
+MANDATORY RULES CHECKLIST:
+================================================================================
+
+[ ] 1. I WILL create a DETAILED todo list using TodoWrite FIRST
+[ ] 2. I WILL run research agent for new features (MANDATORY)
+[ ] 3. I WILL check/create audit documentation
+[ ] 4. I WILL create proper branch (feature/fix/refactor/test)
+[ ] 5. I WILL create SEPARATE UIs for mobile/tablet/desktop (if UI task)
+[ ] 6. I WILL add real-time validation to ALL inputs
+[ ] 7. I WILL document with commit hash references
+[ ] 8. I WILL run quality gates before commit (Husky enforced)
+[ ] 9. I WILL create PR to main with doc references
+[ ] 10. I WILL use Task tool to invoke agents (NOT manually)
+
+================================================================================
+COMPONENT DESIGN RULES (SELF-AWARE RESPONSIVE):
+================================================================================
+
+Components CAN be responsive internally (detect their own device type).
+But layouts MUST be separate for each platform.
+
+CARD COMPONENTS:
+  - NO BORDERS - Use shadows and backgrounds instead
+  - Use useDeviceType() hook for self-awareness
+  - Adapt padding/layout based on device
+  - Desktop: hover effects (scale, shadow)
+  - Mobile: touch-optimized (44px targets)
+
+```typescript
+// GOOD - Self-aware component
+const device = useDeviceType();
+<div className={cn(
+  'rounded-2xl shadow-lg', // NO borders
+  device === 'mobile' ? 'p-4' : 'p-6 hover:scale-[1.02]'
+)} />
+```
+
+================================================================================
+END OF WORKFLOW MANDATORY:
+================================================================================
+
+After completing any task, you MUST:
+
+1. Run commit-manager agent via Task tool
+2. Commit all changes with conventional commit format
+3. Create PR to main if on feature/fix branch
+4. NEVER leave uncommitted changes
+
+This is MANDATORY - workflow is NOT complete until committed.
+
+================================================================================
+"""
+
+    # Return as JSON with decision to continue
     result = {
         "continue": True,
-        "hookSpecificOutput": {
-            "hookEventName": "UserPromptSubmit",
-            "additionalContext": context
-        }
+        "systemMessage": output
     }
 
     print(json.dumps(result))
     sys.exit(0)
 
+
 if __name__ == '__main__':
     main()