--- allowed-tools: all description: Explains how fr3k-claude works in simple terms anyone can understand --- # 👨 /fr3kplease ## Your Complete Guide to Building Better Software This guide shows you **exactly when and how** to use each fr3k-claude command for maximum results. --- ## 🚀 Complete Project Building Workflow **The smartest way to go from idea to working project:** ### Step 1: Initialize Your Project ``` fr3k init ``` **What it does:** Sets up project database and creates `fr3k_project.md` template **When to use:** First thing in any new project (replaces `qlty init`) **Why important:** Enables task tracking and gives you the project planning template ### Step 2: Plan Your Project 1. **Fill out `fr3k_project.md`** with your complete vision: - What you're building (web app, API, CLI tool) - Tech stack preferences (React, Python, etc.) - Key features and requirements - Add design mockups to `./screenshots/` if you have them 2. **Brainstorm with Claude Code** - Discuss your project, ask questions, research best practices 3. **Review everything** - Make sure your `fr3k_project.md` reflects exactly what you want ### Step 3: Generate Your Build Plan ``` /new-project ``` **What it does:** Reads your requirements and creates optimized task sequence **When to use:** After your `fr3k_project.md` is complete and reviewed **Why important:** Creates foundation-first approach with proper dependencies ### Step 4: Build Everything Automatically ``` /start-project ``` **What it does:** Executes all tasks automatically with validation between each step **When to use:** When you're ready to watch AI build your entire project **Why amazing:** Professional results without manual coding --- ## 🛠️ Development Commands - When & Why to Use ### 🏗️ Building New Things ``` /new-feature ``` **What it does:** Creates complete features with tests and documentation **When to use:** Adding new functionality to existing project **Why effective:** Handles frontend, backend, and testing all at once ``` /api ``` **What it does:** Builds complete APIs with security, docs, and testing **When to use:** Need backend endpoints for your application **Why essential:** Professional API design with proper authentication ``` /fr3k-compare ``` **What it does:** Analyzes your project against successful similar projects **When to use:** Want to see how your setup compares to industry standards **Why valuable:** Evidence-based recommendations from real GitHub repositories ### ✅ Quality & Validation ``` /check ``` **What it does:** Finds and fixes ALL problems until everything works perfectly **When to use:** After building new features, before deploying, when things feel broken **Why critical:** Catches errors, style issues, security problems, and performance bottlenecks ``` /prove-it-fr3k ``` **What it does:** Creates simple scripts to validate your business logic actually works **When to use:** After building something new - prove it works before moving on **Why smart:** Quick validation without writing complex tests ``` /ship-it ``` **What it does:** Comprehensive pre-deployment validation across all platforms **When to use:** Before releasing or deploying to production **Why essential:** Ensures your app works everywhere for everyone ### 📦 Code Management ``` /commit ``` **What it does:** Saves changes with professional commit messages following conventions **When to use:** Ready to save your progress with proper git history **Why important:** Maintains clean commit history that other developers understand ``` /clean ``` **What it does:** Removes unused code, files, and dependencies **When to use:** Project feels bloated or you want to reduce bundle size **Why helpful:** Keeps codebase lean and maintainable ### 🔍 Analysis & Planning ``` /plan ``` **What it does:** Breaks complex tasks into manageable steps with clear sequence **When to use:** Facing overwhelming features or architectural decisions **Why useful:** Turns big scary tasks into actionable steps ``` /get-opinion ``` **What it does:** Expert assessment and scoring on technical decisions **When to use:** Unsure about framework choice, architecture, or approach **Why valuable:** Unbiased evaluation based on your specific context ``` /coverage ``` **What it does:** Shows which parts of code are tested and which need attention **When to use:** Want to improve test quality or find untested code paths **Why important:** Identifies risk areas in your application ``` /refactor ``` **What it does:** Safely improves existing code while maintaining functionality **When to use:** Code works but is messy, hard to read, or poorly structured **Why safe:** Uses systematic approach to improve without breaking things ``` /logging ``` **What it does:** Adds helpful logging throughout your application **When to use:** Need to debug issues or monitor application behavior **Why valuable:** Makes troubleshooting much easier when problems occur --- ## ⚙️ Repository Setup (CRITICAL FIRST STEP) Before using fr3k-claude effectively, ensure your repository is properly initialized: 1. **Initialize Git first:** ``` git init git remote add origin https://github.com/your-username/your-repo.git ``` 2. **Then run fr3k initialization:** ``` fr3k init ``` **Why this order matters:** The hey-fr3k MCP needs a proper Git repository to track tasks and maintain databases. Without this setup, task management won't work properly. --- ## 🎯 Typical Development Workflows ### Starting Fresh (New Project) 1. `fr3k init` → Set up tracking and templates 2. Fill out `fr3k_project.md` → Define your vision completely 3. `/new-project` → Generate optimized build plan 4. `/start-project` → Watch AI build your entire project ### Adding to Existing Project 1. `/new-feature` → Add complete functionality with tests 2. `/check` → Validate everything works perfectly 3. `/commit` → Save with professional commit message ### Before Going Live 1. `/fr3k-compare` → See how you stack up against similar projects 2. `/ship-it` → Comprehensive pre-deployment validation 3. `/commit` → Final commit before release ### When Things Break 1. `/check` → Find and fix all problems automatically 2. `/prove-it-fr3k` → Verify your fixes actually work 3. `/commit` → Save the fixes --- ## 💡 Pro Tips for Maximum Results **Always initialize properly:** `git init` + `fr3k init` before starting any serious work **Use the planning workflow:** Don't skip `fr3k_project.md` - the more detail you provide, the better your results **Let quality systems work:** Don't fight the automatic checks - they're designed to save you time **Trust the process:** Commands are designed to work together - follow the suggested workflows **Commit regularly:** Use `/commit` frequently to maintain good version control history --- ## Key Principles - Use conversational, friendly tone - Avoid ALL technical jargon - Focus on benefits and what users get - Use analogies that make sense to non-coders - Keep explanations short and practical --- **Core goal: Make fr3k-claude feel like having a team of experts helping you.**