blockmine 1.20.0 → 1.22.0

package/.claude/skills/skill-developer/HOOK_MECHANISMS.md

@@ -0,0 +1,306 @@
+# Hook Mechanisms - Deep Dive
+
+Technical deep dive into how the UserPromptSubmit and PreToolUse hooks work.
+
+## Table of Contents
+
+- [UserPromptSubmit Hook Flow](#userpromptsubmit-hook-flow)
+- [PreToolUse Hook Flow](#pretooluse-hook-flow)
+- [Exit Code Behavior (CRITICAL)](#exit-code-behavior-critical)
+- [Session State Management](#session-state-management)
+- [Performance Considerations](#performance-considerations)
+
+---
+
+## UserPromptSubmit Hook Flow
+
+### Execution Sequence
+
+```
+User submits prompt
+    ↓
+.claude/settings.json registers hook
+    ↓
+skill-activation-prompt.sh executes
+    ↓
+npx tsx skill-activation-prompt.ts
+    ↓
+Hook reads stdin (JSON with prompt)
+    ↓
+Loads skill-rules.json
+    ↓
+Matches keywords + intent patterns
+    ↓
+Groups matches by priority (critical → high → medium → low)
+    ↓
+Outputs formatted message to stdout
+    ↓
+stdout becomes context for Claude (injected before prompt)
+    ↓
+Claude sees: [skill suggestion] + user's prompt
+```
+
+### Key Points
+
+- **Exit code**: Always 0 (allow)
+- **stdout**: → Claude's context (injected as system message)
+- **Timing**: Runs BEFORE Claude processes prompt
+- **Behavior**: Non-blocking, advisory only
+- **Purpose**: Make Claude aware of relevant skills
+
+### Input Format
+
+```json
+{
+  "session_id": "abc-123",
+  "transcript_path": "/path/to/transcript.json",
+  "cwd": "/root/git/your-project",
+  "permission_mode": "normal",
+  "hook_event_name": "UserPromptSubmit",
+  "prompt": "how does the layout system work?"
+}
+```
+
+### Output Format (to stdout)
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 SKILL ACTIVATION CHECK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📚 RECOMMENDED SKILLS:
+  → project-catalog-developer
+
+ACTION: Use Skill tool BEFORE responding
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Claude sees this output as additional context before processing the user's prompt.
+
+---
+
+## PreToolUse Hook Flow
+
+### Execution Sequence
+
+```
+Claude calls Edit/Write tool
+    ↓
+.claude/settings.json registers hook (matcher: Edit|Write)
+    ↓
+skill-verification-guard.sh executes
+    ↓
+npx tsx skill-verification-guard.ts
+    ↓
+Hook reads stdin (JSON with tool_name, tool_input)
+    ↓
+Loads skill-rules.json
+    ↓
+Checks file path patterns (glob matching)
+    ↓
+Reads file for content patterns (if file exists)
+    ↓
+Checks session state (was skill already used?)
+    ↓
+Checks skip conditions (file markers, env vars)
+    ↓
+IF MATCHED AND NOT SKIPPED:
+  Update session state (mark skill as enforced)
+  Output block message to stderr
+  Exit with code 2 (BLOCK)
+ELSE:
+  Exit with code 0 (ALLOW)
+    ↓
+IF BLOCKED:
+  stderr → Claude sees message
+  Edit/Write tool does NOT execute
+  Claude must use skill and retry
+IF ALLOWED:
+  Tool executes normally
+```
+
+### Key Points
+
+- **Exit code 2**: BLOCK (stderr → Claude)
+- **Exit code 0**: ALLOW
+- **Timing**: Runs BEFORE tool execution
+- **Session tracking**: Prevents repeated blocks in same session
+- **Fail open**: On errors, allows operation (don't break workflow)
+- **Purpose**: Enforce critical guardrails
+
+### Input Format
+
+```json
+{
+  "session_id": "abc-123",
+  "transcript_path": "/path/to/transcript.json",
+  "cwd": "/root/git/your-project",
+  "permission_mode": "normal",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Edit",
+  "tool_input": {
+    "file_path": "/root/git/your-project/form/src/services/user.ts",
+    "old_string": "...",
+    "new_string": "..."
+  }
+}
+```
+
+### Output Format (to stderr when blocked)
+
+```
+⚠️ BLOCKED - Database Operation Detected
+
+📋 REQUIRED ACTION:
+1. Use Skill tool: 'database-verification'
+2. Verify ALL table and column names against schema
+3. Check database structure with DESCRIBE commands
+4. Then retry this edit
+
+Reason: Prevent column name errors in Prisma queries
+File: form/src/services/user.ts
+
+💡 TIP: Add '// @skip-validation' comment to skip future checks
+```
+
+Claude receives this message and understands it needs to use the skill before retrying the edit.
+
+---
+
+## Exit Code Behavior (CRITICAL)
+
+### Exit Code Reference Table
+
+| Exit Code | stdout | stderr | Tool Execution | Claude Sees |
+|-----------|--------|--------|----------------|-------------|
+| 0 (UserPromptSubmit) | → Context | → User only | N/A | stdout content |
+| 0 (PreToolUse) | → User only | → User only | **Proceeds** | Nothing |
+| 2 (PreToolUse) | → User only | → **CLAUDE** | **BLOCKED** | stderr content |
+| Other | → User only | → User only | Blocked | Nothing |
+
+### Why Exit Code 2 Matters
+
+This is THE critical mechanism for enforcement:
+
+1. **Only way** to send message to Claude from PreToolUse
+2. stderr content is "fed back to Claude automatically"
+3. Claude sees the block message and understands what to do
+4. Tool execution is prevented
+5. Critical for enforcement of guardrails
+
+### Example Conversation Flow
+
+```
+User: "Add a new user service with Prisma"
+
+Claude: "I'll create the user service..."
+    [Attempts to Edit form/src/services/user.ts]
+
+PreToolUse Hook: [Exit code 2]
+    stderr: "⚠️ BLOCKED - Use database-verification"
+
+Claude sees error, responds:
+    "I need to verify the database schema first."
+    [Uses Skill tool: database-verification]
+    [Verifies column names]
+    [Retries Edit - now allowed (session tracking)]
+```
+
+---
+
+## Session State Management
+
+### Purpose
+
+Prevent repeated nagging in the same session - once Claude uses a skill, don't block again.
+
+### State File Location
+
+`.claude/hooks/state/skills-used-{session_id}.json`
+
+### State File Structure
+
+```json
+{
+  "skills_used": [
+    "database-verification",
+    "error-tracking"
+  ],
+  "files_verified": []
+}
+```
+
+### How It Works
+
+1. **First edit** of file with Prisma:
+   - Hook blocks with exit code 2
+   - Updates session state: adds "database-verification" to skills_used
+   - Claude sees message, uses skill
+
+2. **Second edit** (same session):
+   - Hook checks session state
+   - Finds "database-verification" in skills_used
+   - Exits with code 0 (allow)
+   - No message to Claude
+
+3. **Different session**:
+   - New session ID = new state file
+   - Hook blocks again
+
+### Limitation
+
+The hook cannot detect when the skill is *actually* invoked - it just blocks once per session per skill. This means:
+
+- If Claude doesn't use the skill but makes a different edit, it won't block again
+- Trust that Claude follows the instruction
+- Future enhancement: detect actual Skill tool usage
+
+---
+
+## Performance Considerations
+
+### Target Metrics
+
+- **UserPromptSubmit**: < 100ms
+- **PreToolUse**: < 200ms
+
+### Performance Bottlenecks
+
+1. **Loading skill-rules.json** (every execution)
+   - Future: Cache in memory
+   - Future: Watch for changes, reload only when needed
+
+2. **Reading file content** (PreToolUse)
+   - Only when contentPatterns configured
+   - Only if file exists
+   - Can be slow for large files
+
+3. **Glob matching** (PreToolUse)
+   - Regex compilation for each pattern
+   - Future: Compile once, cache
+
+4. **Regex matching** (Both hooks)
+   - Intent patterns (UserPromptSubmit)
+   - Content patterns (PreToolUse)
+   - Future: Lazy compile, cache compiled regexes
+
+### Optimization Strategies
+
+**Reduce patterns:**
+- Use more specific patterns (fewer to check)
+- Combine similar patterns where possible
+
+**File path patterns:**
+- More specific = fewer files to check
+- Example: `form/src/services/**` better than `form/**`
+
+**Content patterns:**
+- Only add when truly necessary
+- Simpler regex = faster matching
+
+---
+
+**Related Files:**
+- [SKILL.md](SKILL.md) - Main skill guide
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Debug hook issues
+- [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) - Configuration reference

package/.claude/skills/skill-developer/PATTERNS_LIBRARY.md

@@ -0,0 +1,152 @@
+# Common Patterns Library
+
+Ready-to-use regex and glob patterns for skill triggers. Copy and customize for your skills.
+
+---
+
+## Intent Patterns (Regex)
+
+### Feature/Endpoint Creation
+```regex
+(add|create|implement|build).*?(feature|endpoint|route|service|controller)
+```
+
+### Component Creation
+```regex
+(create|add|make|build).*?(component|UI|page|modal|dialog|form)
+```
+
+### Database Work
+```regex
+(add|create|modify|update).*?(user|table|column|field|schema|migration)
+(database|prisma).*?(change|update|query)
+```
+
+### Error Handling
+```regex
+(fix|handle|catch|debug).*?(error|exception|bug)
+(add|implement).*?(try|catch|error.*?handling)
+```
+
+### Explanation Requests
+```regex
+(how does|how do|explain|what is|describe|tell me about).*?
+```
+
+### Workflow Operations
+```regex
+(create|add|modify|update).*?(workflow|step|branch|condition)
+(debug|troubleshoot|fix).*?workflow
+```
+
+### Testing
+```regex
+(write|create|add).*?(test|spec|unit.*?test)
+```
+
+---
+
+## File Path Patterns (Glob)
+
+### Frontend
+```glob
+frontend/src/**/*.tsx        # All React components
+frontend/src/**/*.ts         # All TypeScript files
+frontend/src/components/**   # Only components directory
+```
+
+### Backend Services
+```glob
+form/src/**/*.ts            # Form service
+email/src/**/*.ts           # Email service
+users/src/**/*.ts           # Users service
+projects/src/**/*.ts        # Projects service
+```
+
+### Database
+```glob
+**/schema.prisma            # Prisma schema (anywhere)
+**/migrations/**/*.sql      # Migration files
+database/src/**/*.ts        # Database scripts
+```
+
+### Workflows
+```glob
+form/src/workflow/**/*.ts              # Workflow engine
+form/src/workflow-definitions/**/*.json # Workflow definitions
+```
+
+### Test Exclusions
+```glob
+**/*.test.ts                # TypeScript tests
+**/*.test.tsx               # React component tests
+**/*.spec.ts                # Spec files
+```
+
+---
+
+## Content Patterns (Regex)
+
+### Prisma/Database
+```regex
+import.*[Pp]risma                # Prisma imports
+PrismaService                    # PrismaService usage
+prisma\.                         # prisma.something
+\.findMany\(                     # Prisma query methods
+\.create\(
+\.update\(
+\.delete\(
+```
+
+### Controllers/Routes
+```regex
+export class.*Controller         # Controller classes
+router\.                         # Express router
+app\.(get|post|put|delete|patch) # Express app routes
+```
+
+### Error Handling
+```regex
+try\s*\{                        # Try blocks
+catch\s*\(                      # Catch blocks
+throw new                        # Throw statements
+```
+
+### React/Components
+```regex
+export.*React\.FC               # React functional components
+export default function.*       # Default function exports
+useState|useEffect              # React hooks
+```
+
+---
+
+**Usage Example:**
+
+```json
+{
+  "my-skill": {
+    "promptTriggers": {
+      "intentPatterns": [
+        "(create|add|build).*?(component|UI|page)"
+      ]
+    },
+    "fileTriggers": {
+      "pathPatterns": [
+        "frontend/src/**/*.tsx"
+      ],
+      "contentPatterns": [
+        "export.*React\\.FC",
+        "useState|useEffect"
+      ]
+    }
+  }
+}
+```
+
+---
+
+**Related Files:**
+- [SKILL.md](SKILL.md) - Main skill guide
+- [TRIGGER_TYPES.md](TRIGGER_TYPES.md) - Detailed trigger documentation
+- [SKILL_RULES_REFERENCE.md](SKILL_RULES_REFERENCE.md) - Complete schema