🚀 FR3K Ultra Setup

Comprehensive Claude Code + FR3KSIK integration with native features, skills, agents, hooks, and cross-platform support

📋 Overview

FR3K Ultra Setup is a complete development environment that extends FR3KSIK with Claude Code's native features:

• 12 Specialized Skills: Validation, transformation, analysis, knowledge, API development, testing, documentation, debugging, security, database, DevOps, and refactoring
• 14 Agents: 6 Claude Code native (bugsy, sherlock, murphy, opinion, scribe, validation) + 8 FR3K methodology (analyst, product, blueprint, forge, qa, devops, scrum, owner)
• 4 Cross-Platform Hooks: Security validation, quality automation, session management
• Platform-Specific Configs: Windows MINGW64, Linux, macOS, WSL

🎯 What You Get

Skills (Model-Invoked Capabilities)

Claude automatically discovers and uses these skills based on context:

| Skill | Purpose | Use When | |-------|---------|----------| | validation-suite | Validate JSON/YAML/XML/regex | User needs data validation | | transformation-suite | Transform formats, encode/decode | User needs format conversion | | analysis-suite | Code quality, security, performance | User requests code review | | knowledge-suite | API docs, protocols, algorithms | User asks "how to" or "what is" | | api-development | Design and implement APIs | User needs API creation | | testing-qa | Generate tests, improve coverage | User needs test generation | | documentation | Create READMEs, API docs, comments | User needs documentation | | debugging | Debug errors, analyze logs | User encounters errors | | security-audit | Security vulnerabilities, OWASP checks | User needs security assessment | | database-operations | Schema design, query optimization | User needs database work | | devops-deployment | CI/CD, containers, infrastructure | User needs deployment | | code-refactoring | Improve structure, reduce complexity | User needs code improvement |

Agents (Specialized Sub-Agents)

Claude Code Native:

• bugsy - Fix errors and crashes
• sherlock - Research docs and APIs
• murphy - Validate configs and dependencies
• opinion - Provide critical feedback with scores
• scribe - Create comprehensive documentation
• validation - Validate against requirements

FR3K Methodology (Full SDLC):

• fr3k-analyst - Business analysis & requirements
• fr3k-product - Product management & prioritization
• fr3k-blueprint - System architecture & design
• fr3k-forge - Master developer implementation
• fr3k-qa - Quality assurance & testing
• fr3k-devops - Deployment & infrastructure
• fr3k-scrum - Workflow coordination
• fr3k-owner - Final validation & sign-off

Hooks (Automation)

PreToolUse (Security):

• Blocks dangerous rm -rf commands
• Prevents access to .env files
• Blocks superuser commands
• Validates command safety

PostToolUse (Quality):

• Auto-formats code (prettier, black)
• Validates file quality
• Checks for trailing whitespace
• Detects TODO comments

SessionStart/SessionEnd:

• Welcome messages with system info
• Cleanup reminders
• Session tracking

🚀 Quick Start

Installation

# Install globally
npx fr3k-ultra-setup install --scope=user

# Install for current project
npx fr3k-ultra-setup install --scope=project

# Install specific components
npx fr3k-ultra-setup install --skills
npx fr3k-ultra-setup install --agents
npx fr3k-ultra-setup install --hooks
npx fr3k-ultra-setup install --settings

Verification

# Verify installation
npx fr3k-ultra-setup verify

# Show platform info
npx fr3k-ultra-setup info

Post-Installation

1. Restart Claude Code to load new configuration
2. Verify MCP servers: Run /mcp command in Claude Code
3. Test skills: Ask Claude to "validate this JSON: {test: 1}"
4. Test agents: Use @bugsy or @sherlock in your prompts

📦 What Gets Installed

.claude/
├── skills/                    # 12 specialized skills
│   ├── validation-suite/
│   ├── transformation-suite/
│   ├── analysis-suite/
│   ├── knowledge-suite/
│   ├── api-development/
│   ├── testing-qa/
│   ├── documentation/
│   ├── debugging/
│   ├── security-audit/
│   ├── database-operations/
│   ├── devops-deployment/
│   └── code-refactoring/
├── agents/                    # 14 agents
│   ├── bugsy.md
│   ├── sherlock.md
│   ├── murphy.md
│   ├── opinion.md
│   ├── scribe.md
│   ├── validation.md
│   ├── fr3k-analyst.md
│   ├── fr3k-product.md
│   ├── fr3k-blueprint.md
│   ├── fr3k-forge.md
│   ├── fr3k-qa.md
│   ├── fr3k-devops.md
│   ├── fr3k-scrum.md
│   └── fr3k-owner.md
├── hooks/                     # 4 hook scripts
│   ├── pre_tool_use.py       # Security validation
│   ├── post_tool_use.py      # Quality automation
│   ├── session_start.py      # Welcome message
│   └── session_end.py        # Cleanup reminders
└── settings.json             # Platform-specific config

🖥️ Platform Support

Windows MINGW64

• Auto-detected
• Uses cmd /c wrapper for MCP servers
• Python hooks with fallback handling
• PATH handling for Git Bash environment

Linux

• Native npx support
• Direct hook execution
• Standard shell environment

macOS

• Native npx support
• Direct hook execution
• Standard shell environment

WSL (Windows Subsystem for Linux)

• Auto-detected as Linux
• Better performance than MINGW64
• Recommended for Windows users

🔧 Configuration

MCP Servers (Auto-Configured)

The installer automatically configures these MCP servers with platform-specific wrappers:

• hey-fr3k: Task & memory management
• fr3k-think: Complex reasoning protocol
• md-mcp: Markdown processing & tool creation
• unified-pantheon-mcp: 72 Demon-Angel pairs & dual patterns

Permissions (Security)

Allowed:

• All standard tools (Bash, Read, Write, Edit, Grep, Glob)
• Web tools (WebFetch, WebSearch)
• All MCP server tools

Denied:

• rm -rf commands
• git push --force
• Reading/writing .env files

Hooks (Automation)

Hooks run automatically and are cross-platform compatible:

• PreToolUse: Validates every tool call before execution
• PostToolUse: Auto-formats files after Write/Edit
• SessionStart: Shows welcome message with system info
• SessionEnd: Reminds about commits and tests

📚 Usage Examples

Using Skills

Skills are automatically invoked by Claude based on your request:

You: "Can you validate this JSON: {name: 'test'}"
Claude: [Uses validation-suite skill]
❌ Invalid JSON
Error: Property names must be in double quotes
Corrected: {"name": "test"}

You: "Convert this JSON to YAML: {name: 'test', age: 25}"
Claude: [Uses transformation-suite skill]
✅ Converted JSON → YAML
Output:
name: test
age: 25

Using Agents

Invoke agents with @-mentions:

You: "@bugsy fix this error: Cannot read property 'name' of undefined"
[Bugsy agent spawns]
- Analyzes error
- Identifies root cause
- Implements fix with test
- Verifies solution

You: "@sherlock find the best package for date formatting"
[Sherlock agent spawns]
- Researches packages
- Compares options
- Provides recommendation with examples

FR3K Workflow

Use FR3K agents for complete project lifecycle:

You: "@fr3k-analyst analyze requirements for task management app"
[FR3K Analyst gathers requirements]

You: "@fr3k-product prioritize features for MVP"
[FR3K Product creates product plan]

You: "@fr3k-blueprint design the architecture"
[FR3K Blueprint creates technical design]

You: "@fr3k-forge implement the API endpoints"
[FR3K Forge writes production code]

You: "@fr3k-qa write comprehensive tests"
[FR3K QA creates test suite]

You: "@fr3k-devops setup CI/CD pipeline"
[FR3K DevOps configures deployment]

You: "@fr3k-owner validate against requirements"
[FR3K Owner provides final sign-off]

🛠️ Troubleshooting

MCP Servers Not Loading (Windows)

Symptom: Warnings about "Windows requires 'cmd /c' wrapper"

Solution:

# Reinstall with correct platform detection
npx fr3k-ultra-setup install --settings

The installer automatically adds cmd /c wrapper for Windows MINGW64.

Hooks Not Executing

Symptom: Hooks don't run or fail silently

Solution:

1. Verify Python is installed: python --version
2. Check hook scripts are in .claude/hooks/
3. On Unix, ensure scripts are executable: chmod +x .claude/hooks/*.py
4. Check Claude Code settings for hook configuration

Skills Not Being Used

Symptom: Claude doesn't use skills automatically

Solution:

1. Verify skills are in .claude/skills/
2. Check YAML frontmatter has name and description fields
3. Restart Claude Code to reload skills
4. Skills are model-invoked - Claude decides when to use them

Agents Not Available

Symptom: @-mentions don't work

Solution:

1. Verify agents are in .claude/agents/
2. Check YAML frontmatter is correct
3. Restart Claude Code
4. Use /agents command to see available agents

🔍 Advanced Usage

Custom Skills

Create your own skills in .claude/skills/your-skill/SKILL.md:

---
name: your-skill
description: What it does and when to use it
---

# Your Skill Name

## Instructions
[How to use this skill]

## Examples
[Usage examples]

Custom Agents

Create custom agents in .claude/agents/your-agent.md:

---
name: your-agent
description: What this agent does
tools: Read, Write, Bash
model: inherit
---

# Your Agent Name

You are [description]...

## Your Responsibilities
1. [Task 1]
2. [Task 2]

Custom Hooks

Add custom hooks to .claude/hooks/:

#!/usr/bin/env python3
import json, sys

data = json.load(sys.stdin)
# Your logic here
sys.exit(0)  # 0=allow, 1=silent fail, 2=block

Then add to settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "python .claude/hooks/your_hook.py"
      }]
    }]
  }
}

🤝 Integration with FR3KSIK

FR3K Ultra Setup extends and complements npx fr3ksik:

1. Run FR3KSIK first (optional): npx fr3ksik init
2. Then run Ultra Setup: npx fr3k-ultra-setup install

Ultra Setup adds:

• Claude Code native features (skills system)
• Enhanced agents with workflow integration
• Cross-platform hook automation
• Platform-specific optimizations

📊 Feature Comparison

| Feature | FR3KSIK | Ultra Setup | Combined | |---------|---------|-------------|----------| | MCP Servers | 4 core | 4 core | 4 core | | Agents | 8 FR3K | 6 + 8 = 14 | 14 total | | Skills | - | 12 | 12 | | Hooks | Examples | 4 production | 4 production | | Platform Support | Basic | Advanced | Advanced | | Windows MINGW64 | Manual | Auto | Auto |

🛡️ Security

Built-In Security

• Input Validation: All user input validated before use
• Secret Protection: Blocks access to .env and credential files
• Command Filtering: Dangerous commands automatically blocked
• Least Privilege: Tools have minimal required permissions

Security Hooks

PreToolUse hook blocks:

• rm -rf commands
• Superuser commands (sudo, su)
• Piping curl/wget to bash
• Writing to system files
• Accessing secret files

Best Practices

1. Never commit .env files or secrets
2. Review hook logs regularly
3. Keep hooks enabled (don't disable security)
4. Use environment variables for secrets
5. Test security in development first

📈 Performance

Skills Performance

• Token-efficient: Only 30-50 tokens until loaded
• Model-invoked: Claude decides when to use
• Instant availability: No network calls

Agents Performance

• Isolated contexts: Don't pollute main conversation
• Parallel capable: Can run multiple agents
• Optimized tools: Only necessary tools available

Hooks Performance

• Python-based: Fast execution
• Non-blocking: Use exit code 0 for warnings
• Cached: Frequently used patterns cached

🔄 Updates

Updating FR3K Ultra Setup

# Reinstall to update
npx fr3k-ultra-setup install --scope=project

# Or update specific components
npx fr3k-ultra-setup install --skills
npx fr3k-ultra-setup install --agents

Backup Before Update

The installer automatically creates backups:

• settings.backup.json - Previous settings

🐛 Known Issues

Windows MINGW64

• Issue: npx commands slow to start
• Workaround: Use WSL for better performance

Path Handling

• Issue: Spaces in paths on Windows
• Workaround: Use quotes: "path with spaces"

Hook Failures

• Issue: Hooks fail and block work
• Workaround: Add || true to hook commands

💡 Tips & Tricks

Tip 1: Use Skills Liberally

Don't tell Claude to use skills - just ask naturally:

• ✅ "Validate this JSON"
• ❌ "Use validation-suite to validate this JSON"

Tip 2: Combine Agents

Spawn multiple agents for complex tasks:

@sherlock research authentication methods
@fr3k-blueprint design auth architecture
@fr3k-forge implement authentication
@fr3k-qa write auth tests

Tip 3: Customize for Your Team

• Add team-specific skills
• Create project-specific agents
• Configure hooks for your workflow
• Share .claude/ folder in git

Tip 4: Monitor Security Hooks

Check hook logs to understand what's being blocked:

# View recent blocks
tail -f ~/.claude/logs/hooks.log

📞 Support

• Documentation: This README
• Issues: https://github.com/fr3k/fr3k-ultra-setup/issues
• FR3KSIK: https://github.com/fr3k/fr3ksik
• Claude Code: https://docs.claude.com/en/docs/claude-code

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Built on FR3KSIK by FR3K Intelligence
• Integrates with Claude Code by Anthropic
• Uses md-mcp for dynamic tool creation
• Inspired by the Unified Pantheon Framework

🚀 What's Next

• [ ] OpenCode full compatibility
• [ ] Additional skills (frontend, mobile, ML)
• [ ] Agent marketplace
• [ ] Hook library
• [ ] VS Code extension
• [ ] Cloud sync for settings

Made with ⚡ by FR3K Intelligence