@aslomon/effectum 0.3.4 → 0.5.0

package/system/agents/mobile-developer.md

@@ -0,0 +1,257 @@
+---
+name: mobile-developer
+description: "Use this agent when building mobile applications with React Native, Flutter, Expo, or native iOS/Android. Invoke for cross-platform development, responsive design, app store compliance, mobile performance optimization, and platform-specific implementation patterns."
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+You are a senior mobile developer specializing in cross-platform and native mobile application development. Your expertise spans React Native, Flutter, Expo, Swift/SwiftUI, and Kotlin/Jetpack Compose, with deep knowledge of mobile UX patterns, performance optimization, and app store guidelines.
+
+When invoked:
+
+1. Query context manager for existing mobile architecture and platform targets
+2. Review project structure, navigation patterns, and state management
+3. Analyze platform-specific requirements and constraints
+4. Design following mobile-first principles and platform conventions
+
+Mobile development checklist:
+
+- Platform targets identified (iOS, Android, both)
+- Navigation architecture defined
+- State management approach chosen
+- Offline support considered
+- Push notifications planned
+- Deep linking configured
+- App permissions documented
+- Performance budgets set
+
+React Native expertise:
+
+- New Architecture (Fabric, TurboModules)
+- Metro bundler configuration
+- Native module bridging
+- Hermes engine optimization
+- CodePush / OTA updates
+- React Navigation patterns
+- Reanimated animations
+- Gesture handler integration
+
+Flutter expertise:
+
+- Widget composition patterns
+- Riverpod / Bloc state management
+- Platform channels
+- Custom render objects
+- Dart isolates for compute
+- Material 3 / Cupertino widgets
+- Custom painting and effects
+- Build flavors and environments
+
+Expo expertise:
+
+- Managed vs bare workflow
+- EAS Build and Submit
+- Expo Router navigation
+- Config plugins
+- Custom dev clients
+- Prebuild architecture
+- Over-the-air updates
+- Module API patterns
+
+Native iOS (Swift/SwiftUI):
+
+- SwiftUI view composition
+- Combine / async-await
+- Core Data / SwiftData
+- UIKit interop
+- App Intents and Shortcuts
+- WidgetKit extensions
+- StoreKit 2 in-app purchases
+- XCTest and UI testing
+
+Native Android (Kotlin):
+
+- Jetpack Compose
+- Kotlin coroutines / Flow
+- Room database
+- Hilt dependency injection
+- WorkManager background tasks
+- Material Design 3
+- Play Billing Library
+- Instrumented testing
+
+Responsive design:
+
+- Adaptive layouts for phones and tablets
+- Safe area handling
+- Dynamic type / font scaling
+- Orientation changes
+- Foldable device support
+- Platform-specific spacing
+- Accessibility sizing
+- Dark mode support
+
+Performance optimization:
+
+- Startup time optimization
+- List virtualization (FlatList, RecyclerView)
+- Image caching and lazy loading
+- Bundle size reduction
+- Memory leak detection
+- Frame rate monitoring
+- Network request batching
+- Background task management
+
+App store guidelines:
+
+- Apple App Store Review Guidelines
+- Google Play Store policies
+- Privacy policy requirements
+- Data collection disclosure
+- In-app purchase rules
+- Content rating compliance
+- Accessibility requirements
+- Screenshot and metadata preparation
+
+Security considerations:
+
+- Secure storage (Keychain, Keystore)
+- Certificate pinning
+- Biometric authentication
+- JWT token management
+- Code obfuscation
+- Jailbreak/root detection
+- Secure networking (TLS)
+- Data encryption at rest
+
+## Communication Protocol
+
+### Mobile Architecture Assessment
+
+Initialize mobile development by understanding the project scope and platform targets.
+
+Architecture context request:
+
+```json
+{
+  "requesting_agent": "mobile-developer",
+  "request_type": "get_mobile_context",
+  "payload": {
+    "query": "Mobile development context needed: target platforms, framework choice, navigation requirements, offline needs, push notification strategy, and performance constraints."
+  }
+}
+```
+
+## Development Workflow
+
+Execute mobile development through systematic phases:
+
+### 1. Platform Analysis
+
+Understand target platforms and technical constraints.
+
+Analysis framework:
+
+- Platform target matrix
+- Device compatibility range
+- OS version support
+- Feature parity requirements
+- Platform-specific features
+- Third-party SDK needs
+- Build and distribution plan
+- Testing device coverage
+
+Platform evaluation:
+
+- Cross-platform vs native trade-offs
+- Performance requirements
+- Native API access needs
+- Team expertise alignment
+- Time-to-market constraints
+- Maintenance considerations
+- User experience expectations
+- Budget and resource planning
+
+### 2. Implementation Phase
+
+Build mobile features with platform awareness.
+
+Implementation approach:
+
+- Component architecture design
+- Navigation flow implementation
+- State management setup
+- API integration layer
+- Offline data strategy
+- Push notification setup
+- Deep link configuration
+- Platform-specific adaptations
+
+Progress reporting:
+
+```json
+{
+  "agent": "mobile-developer",
+  "status": "implementing",
+  "mobile_progress": {
+    "screens": 12,
+    "navigation_flows": 4,
+    "api_integrations": 8,
+    "platform_coverage": "iOS + Android",
+    "test_coverage": "75%"
+  }
+}
+```
+
+### 3. Quality and Distribution
+
+Ensure app quality and prepare for distribution.
+
+Quality checklist:
+
+- All screens responsive
+- Accessibility audit passed
+- Performance benchmarks met
+- Offline mode tested
+- Push notifications working
+- Deep links verified
+- App store screenshots ready
+- Privacy compliance verified
+
+Delivery notification:
+"Mobile development completed. Built cross-platform application with 12 screens, offline support, push notifications, and biometric authentication. Performance: cold start < 2s, 60fps scrolling. Ready for App Store and Play Store submission."
+
+Testing strategies:
+
+- Unit tests for business logic
+- Component snapshot tests
+- Integration tests for flows
+- E2E tests (Detox, Maestro)
+- Device farm testing
+- Accessibility testing
+- Performance profiling
+- Beta distribution (TestFlight, Firebase)
+
+CI/CD for mobile:
+
+- Fastlane automation
+- EAS Build pipelines
+- Code signing management
+- Version bump automation
+- Beta distribution
+- Store submission automation
+- Release notes generation
+- Crash monitoring setup
+
+Integration with other agents:
+
+- Collaborate with ui-designer on mobile UI patterns
+- Work with backend-developer on API contracts
+- Coordinate with security-engineer on mobile security
+- Partner with test-automator on mobile testing strategy
+- Consult performance-engineer on mobile performance
+- Sync with devops-engineer on CI/CD pipelines
+- Align with api-designer on mobile-optimized endpoints
+- Engage fullstack-developer on shared logic
+
+Always prioritize user experience, platform conventions, performance, and accessibility while delivering high-quality mobile applications that meet app store requirements.

package/system/templates/CLAUDE.md.tmpl

@@ -72,6 +72,10 @@
 | `/ralph-loop`     | Full Auto      | Iterative autonomous implementation      |
 
 
+## Available CLI Tools
+
+{{AVAILABLE_TOOLS}}
+
 ## Context7 — Always Use for Research
 
 - Always use Context7 MCP (`resolve_library_id` -> `get_library_docs`) when:
@@ -96,6 +100,8 @@ The following hooks run automatically. Do NOT duplicate their behavior:
 - **Guardrails Injection**: At session start and after compaction, `~/.claude/guardrails.md` (global) and `$PROJECT/.claude/guardrails.md` (project) are loaded. Follow them strictly.
 - **Transcript Backup**: Transcripts are backed up before context compaction to `.claude/backups/`.
 - **Protected Files**: `.env`, `.env.local`, `.env.production`, `secrets/`, `.git/`, lock files cannot be written to. Use Bash for env file operations if absolutely needed.
+- **Secret Detection**: Before `git commit` and `git push`, staged changes are scanned for API keys, tokens, and passwords. Blocked if secrets found.
+- **TDD Enforcement**: Before stopping, checks that test files were modified alongside source files. Blocks if source changed without tests.
 - **Destructive Command Blocker**: `rm -rf /`, `DROP TABLE`, `--force push`, `reset --hard` are blocked.
 - **Desktop Notifications**: User gets OS notifications on permission prompts and task completion.
 

package/system/templates/settings.json.tmpl

@@ -71,6 +71,11 @@
             "type": "command",
             "command": "bash -c 'CMD=$(jq -r \".tool_input.command\" <<< \"$(cat)\"); if echo \"$CMD\" | grep -qE \"^git commit\"; then MSG=$(echo \"$CMD\" | grep -oP \"(?<=-m \\\")[^\\\"]+|(?<=-m \\x27)[^\\x27]+\" || echo \"\"); if [ -n \"$MSG\" ] && [ ${#MSG} -lt 10 ]; then echo \"Commit message too short (min 10 chars). Be descriptive.\" >&2; exit 2; fi; fi; exit 0'",
             "statusMessage": "Checking commit message..."
+          },
+          {
+            "type": "command",
+            "command": "bash -c 'CMD=$(jq -r \".tool_input.command\" <<< \"$(cat)\"); if echo \"$CMD\" | grep -qE \"^git (commit|push)\"; then DIFF=$(git diff --cached --diff-filter=ACM 2>/dev/null || git diff HEAD 2>/dev/null); if echo \"$DIFF\" | grep -qEi \"(sk-[a-zA-Z0-9]{20,}|sk_live_|sk_test_|AKIA[A-Z0-9]{16}|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9-]{20}|xox[bpras]-[a-zA-Z0-9-]+|password\\s*[:=]\\s*[\\x27\\\"][^\\x27\\\"]{8,})\"; then echo \"Potential secret detected in staged changes! Review before committing.\" >&2; exit 2; fi; fi; exit 0'",
+            "statusMessage": "Scanning for secrets..."
           }
         ]
       }
@@ -130,6 +135,12 @@
             "timeout": 30,
             "statusMessage": "Verifying work completion..."
           },
+          {
+            "type": "prompt",
+            "prompt": "Check if tests were written for code changes. Run: git diff --name-only HEAD 2>/dev/null\n\nAnalyze the changed files:\n1. Identify source code files (not config, not docs, not tests)\n2. Check if corresponding test files were also changed or created\n3. If source files changed but NO test files changed, respond {\"ok\": false, \"reason\": \"Source files were modified but no tests were written. Write tests before stopping.\"}\n4. If tests exist for the changes, or only config/docs changed, respond {\"ok\": true}\n5. If stop_hook_active is true in input, be lenient — only block for completely untested new features.\n\nContext: $ARGUMENTS",
+            "timeout": 30,
+            "statusMessage": "Checking test coverage..."
+          },
           {
             "type": "agent",
             "prompt": "Check if meaningful code changes were made in this session by running: git diff --stat HEAD 2>/dev/null\n\nIf there are staged or unstaged changes to source code files (not just config/formatting):\n1. Read the current CHANGELOG.md if it exists\n2. Add entries under [Unreleased] following Keep a Changelog format (Added/Changed/Fixed/Removed)\n3. If CHANGELOG.md doesn't exist, create it with a proper header and the current changes\n\nIf changes are trivial (only formatting, only comments, only config), skip and respond {\"ok\": true}.\nIf stop_hook_active is true, respond {\"ok\": true} immediately — do not update CHANGELOG on second pass.\n\nContext: $ARGUMENTS",

package/system/tools/_schema.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Effectum Tool Definition",
+  "description": "Schema for tool definition files in system/tools/. Each file defines tools for a specific stack or category.",
+  "type": "object",
+  "required": ["tools"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Human-readable name for this tool set (e.g., 'Foundation Tools')"
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of when these tools are used"
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "key",
+          "bin",
+          "displayName",
+          "category",
+          "why",
+          "priority"
+        ],
+        "properties": {
+          "key": {
+            "type": "string",
+            "description": "Unique identifier for the tool (e.g., 'git', 'supabase')"
+          },
+          "bin": {
+            "type": "string",
+            "description": "Binary name to check in PATH (e.g., 'git', 'supabase')"
+          },
+          "displayName": {
+            "type": "string",
+            "description": "Human-readable name (e.g., 'Supabase CLI')"
+          },
+          "category": {
+            "type": "string",
+            "enum": ["system", "foundation", "stack", "optional"],
+            "description": "Tool category: system (OS-level), foundation (always needed), stack (stack-specific), optional (nice-to-have)"
+          },
+          "why": {
+            "type": "string",
+            "description": "Human-readable reason why this tool is needed"
+          },
+          "priority": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 10,
+            "description": "Installation priority (0 = highest, 10 = lowest). Determines install order."
+          },
+          "autoInstall": {
+            "type": "boolean",
+            "default": true,
+            "description": "If false, tool is recommended with a link but not auto-installed (e.g., Docker, Xcode)"
+          },
+          "install": {
+            "type": "object",
+            "properties": {
+              "darwin": {
+                "type": "string",
+                "description": "macOS install command"
+              },
+              "linux": {
+                "type": "string",
+                "description": "Linux install command"
+              },
+              "all": {
+                "type": "string",
+                "description": "Cross-platform install command"
+              }
+            },
+            "description": "Platform-specific install commands. 'all' is used as fallback."
+          },
+          "check": {
+            "type": "string",
+            "description": "Command to verify the tool is working (e.g., 'git --version'). Falls back to 'which <bin>'."
+          },
+          "manualUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "URL for manual installation instructions (used when autoInstall is false)"
+          },
+          "auth": {
+            "type": "object",
+            "properties": {
+              "check": {
+                "type": "string",
+                "description": "Command to check auth status (exit 0 = authenticated)"
+              },
+              "setup": {
+                "type": "string",
+                "description": "Command to set up authentication"
+              },
+              "url": {
+                "type": "string",
+                "format": "uri",
+                "description": "URL where user can create tokens/credentials"
+              }
+            },
+            "required": ["check", "setup"],
+            "description": "Authentication configuration. Omit if tool needs no auth."
+          }
+        }
+      }
+    }
+  }
+}

package/system/tools/foundation.json

@@ -0,0 +1,56 @@
+{
+  "name": "Foundation Tools",
+  "description": "Always-required tools regardless of stack. Loaded for every project.",
+  "tools": [
+    {
+      "key": "git",
+      "bin": "git",
+      "displayName": "Git",
+      "category": "foundation",
+      "why": "Version control — required for all projects",
+      "priority": 0,
+      "autoInstall": true,
+      "install": {
+        "darwin": "xcode-select --install",
+        "linux": "sudo apt install -y git"
+      },
+      "check": "git --version",
+      "auth": {
+        "check": "git config user.name && git config user.email",
+        "setup": "git config --global user.name \"Your Name\" && git config --global user.email \"you@example.com\""
+      }
+    },
+    {
+      "key": "gh",
+      "bin": "gh",
+      "displayName": "GitHub CLI",
+      "category": "foundation",
+      "why": "GitHub: Issues, PRs, Code Search, CI status",
+      "priority": 1,
+      "autoInstall": true,
+      "install": {
+        "darwin": "brew install gh",
+        "linux": "sudo apt install -y gh"
+      },
+      "check": "gh --version",
+      "auth": {
+        "check": "gh auth status",
+        "setup": "gh auth login",
+        "url": "https://github.com/settings/tokens"
+      }
+    },
+    {
+      "key": "claude",
+      "bin": "claude",
+      "displayName": "Claude Code",
+      "category": "foundation",
+      "why": "AI coding agent — the core of the autonomous workflow",
+      "priority": 0,
+      "autoInstall": true,
+      "install": {
+        "all": "npm i -g @anthropic-ai/claude-code"
+      },
+      "check": "claude --version"
+    }
+  ]
+}

package/system/tools/generic.json

@@ -0,0 +1,20 @@
+{
+  "name": "Generic Tools",
+  "description": "Minimal optional tools for generic or undetected stacks.",
+  "tools": [
+    {
+      "key": "jq",
+      "bin": "jq",
+      "displayName": "jq",
+      "category": "optional",
+      "why": "JSON processing on the command line",
+      "priority": 5,
+      "autoInstall": true,
+      "install": {
+        "darwin": "brew install jq",
+        "linux": "sudo apt install -y jq"
+      },
+      "check": "jq --version"
+    }
+  ]
+}

package/system/tools/nextjs-supabase.json

@@ -0,0 +1,56 @@
+{
+  "name": "Next.js + Supabase Tools",
+  "description": "Tools for Next.js with Supabase stack projects.",
+  "tools": [
+    {
+      "key": "pnpm",
+      "bin": "pnpm",
+      "displayName": "pnpm",
+      "category": "stack",
+      "why": "Fast, disk-efficient package manager for Node.js",
+      "priority": 1,
+      "autoInstall": true,
+      "install": {
+        "all": "npm i -g pnpm"
+      },
+      "check": "pnpm --version"
+    },
+    {
+      "key": "supabase",
+      "bin": "supabase",
+      "displayName": "Supabase CLI",
+      "category": "stack",
+      "why": "Database migrations, type generation, edge functions",
+      "priority": 2,
+      "autoInstall": true,
+      "install": {
+        "darwin": "brew install supabase/tap/supabase",
+        "linux": "npm i -g supabase"
+      },
+      "check": "supabase --version",
+      "auth": {
+        "check": "supabase projects list 2>&1 | head -1",
+        "setup": "supabase login",
+        "url": "https://supabase.com/dashboard/account/tokens"
+      }
+    },
+    {
+      "key": "vercel",
+      "bin": "vercel",
+      "displayName": "Vercel CLI",
+      "category": "stack",
+      "why": "Deployment to Vercel",
+      "priority": 3,
+      "autoInstall": true,
+      "install": {
+        "all": "npm i -g vercel"
+      },
+      "check": "vercel --version",
+      "auth": {
+        "check": "vercel whoami",
+        "setup": "vercel login",
+        "url": "https://vercel.com/account/tokens"
+      }
+    }
+  ]
+}

package/system/tools/python-fastapi.json

@@ -0,0 +1,47 @@
+{
+  "name": "Python + FastAPI Tools",
+  "description": "Tools for Python with FastAPI stack projects.",
+  "tools": [
+    {
+      "key": "uv",
+      "bin": "uv",
+      "displayName": "uv",
+      "category": "stack",
+      "why": "Fast Python package management",
+      "priority": 1,
+      "autoInstall": true,
+      "install": {
+        "all": "curl -LsSf https://astral.sh/uv/install.sh | sh"
+      },
+      "check": "uv --version"
+    },
+    {
+      "key": "ruff",
+      "bin": "ruff",
+      "displayName": "Ruff",
+      "category": "stack",
+      "why": "Python linting and formatting",
+      "priority": 2,
+      "autoInstall": true,
+      "install": {
+        "all": "pip install ruff"
+      },
+      "check": "ruff --version"
+    },
+    {
+      "key": "docker",
+      "bin": "docker",
+      "displayName": "Docker",
+      "category": "stack",
+      "why": "Container management, local dev environment",
+      "priority": 5,
+      "autoInstall": false,
+      "install": {
+        "darwin": "brew install --cask docker",
+        "linux": "sudo apt install -y docker.io"
+      },
+      "check": "docker --version",
+      "manualUrl": "https://docs.docker.com/get-docker/"
+    }
+  ]
+}

package/system/tools/swift-ios.json

@@ -0,0 +1,33 @@
+{
+  "name": "Swift / iOS Tools",
+  "description": "Tools for Swift and iOS/macOS development.",
+  "tools": [
+    {
+      "key": "xcode-select",
+      "bin": "xcodebuild",
+      "displayName": "Xcode Command Line Tools",
+      "category": "stack",
+      "why": "iOS/macOS build toolchain",
+      "priority": 0,
+      "autoInstall": false,
+      "install": {
+        "darwin": "xcode-select --install"
+      },
+      "check": "xcodebuild -version",
+      "manualUrl": "https://developer.apple.com/xcode/"
+    },
+    {
+      "key": "swift-format",
+      "bin": "swift-format",
+      "displayName": "swift-format",
+      "category": "stack",
+      "why": "Swift code formatting",
+      "priority": 2,
+      "autoInstall": true,
+      "install": {
+        "darwin": "brew install swift-format"
+      },
+      "check": "swift-format --version"
+    }
+  ]
+}