jettypod 3.0.1

package/docs/features/jettypod-standards-explained.md

@@ -0,0 +1,543 @@
+# JettyPod Standards System - How It Works
+
+## What Is This?
+
+JettyPod Standards is like a recipe book for writing code. Just like how a restaurant has standards for how to prepare dishes (always salt the pasta water, never overcook the steak), software projects need standards for how to write code (always name files this way, always handle errors that way).
+
+When you're working with Claude (the AI assistant), JettyPod Standards makes sure Claude follows YOUR project's rules, not generic ones.
+
+---
+
+## The Big Picture
+
+Imagine you're building a house with a team. You need everyone to agree on:
+- Which way doors should open
+- What color the walls should be
+- How high the ceilings should be
+
+JettyPod Standards does this for code. It tells Claude:
+- How to name your files
+- How to structure your code
+- What patterns to follow
+- What to avoid
+
+---
+
+## How to Get Started
+
+### First Time Setup
+
+1. **Go to your project folder** (where your code lives)
+
+2. **Type this command:**
+   ```
+   jettypod standards init
+   ```
+
+3. **What happens:**
+   - JettyPod looks at your project and figures out what kind it is (like a website, an app, or a server)
+     - **How it figures this out:**
+       - First, it looks for a `package.json` file (the file that lists what tools your project uses)
+       - It checks what frameworks you have installed:
+         - If it sees "next" → It's a Next.js website
+         - If it sees "react" → It's a React app
+         - If it sees "express" → It's a server/API
+         - If it sees "vue" → It's a Vue.js app
+       - If there's no package.json, it looks for other clues:
+         - `next.config.js` file → Next.js project
+         - `vite.config.js` file → Vite project
+         - `index.html` file → Basic website
+       - If it can't figure it out → It just adds basic universal standards
+   - It automatically adds a starter set of rules based on what it found
+   - It creates a special file (CLAUDE.md) that Claude reads
+   - You see a message like "8 standards now active"
+
+That's it! Claude now knows your project's rules.
+
+---
+
+## When Are Bundles Added to Your Toolbox?
+
+Bundles get added to your project in different ways depending on what you're doing:
+
+### Automatic Addition (JettyPod Decides for You)
+
+**When you first initialize (`jettypod standards init`):**
+JettyPod looks at your project and automatically adds appropriate bundles:
+
+- **Next.js project detected** → Adds: core + nextjs + ui bundles
+- **React app detected** → Adds: core + ui + forms bundles  
+- **Node API detected** → Adds: core + node_api + api bundles
+- **Vue app detected** → Adds: core + ui + forms bundles
+- **Express server detected** → Adds: core + api + database bundles
+- **Can't detect type** → Adds: core bundle only (the basics)
+
+This happens automatically - you don't have to choose anything!
+
+### Manual Addition (You Choose)
+
+**When you want specific features:**
+```
+jettypod standards add auth
+```
+This adds authentication standards when YOU decide you need them.
+
+**Common manual additions:**
+- `add shadcn` - When using shadcn/ui component library
+- `add auth` - When you're building login features
+- `add api` - When you're creating server endpoints
+- `add database` - When you're working with data storage
+- `add forms` - When you're building user input features
+- `add testing` - When you want to write tests
+
+### Mode-Related Bundles
+
+When you switch modes, JettyPod doesn't add new bundles - it just changes how Claude sees your existing bundles:
+- **Speed mode** → Shows only critical standards from your bundles
+- **Discovery mode** → Shows all standards with examples
+- **Production mode** → Shows everything in full detail
+
+**Important:** Switching modes doesn't add or remove bundles - it just changes the presentation!
+
+### Smart Context Detection (Coming Soon)
+
+In the future, JettyPod will automatically suggest bundles based on what you're working on:
+
+**How it will work:**
+- You start writing login code → JettyPod suggests: "Add auth bundle?"
+- You create a database schema → JettyPod suggests: "Add database bundle?"
+- You build an API endpoint → JettyPod suggests: "Add api bundle?"
+- You write your first test → JettyPod suggests: "Add testing bundle?"
+
+**Why this doesn't exist yet:**
+JettyPod can't currently watch what files you're editing or what code you're writing. Once integrated deeper with your editor, it could detect patterns like:
+- Files named `login.js` or `auth.tsx` → Suggest auth bundle
+- Files with SQL queries → Suggest database bundle
+- Files with `test` in the name → Suggest testing bundle
+- API route files → Suggest api bundle
+
+For now, you need to manually add bundles when you know you'll need them.
+
+---
+
+## What Are "Bundles"?
+
+Think of bundles like themed packages of rules. Instead of choosing 50 individual rules, you pick a few bundles that make sense together.
+
+### Examples of Bundles:
+
+**Core Bundle** (The Basics)
+- How to name files (UserProfile.tsx not user-profile.tsx)
+- How to name variables (isLoading not loading)
+- How to write commit messages (feat: added login not "fixed stuff")
+
+**Auth Bundle** (For User Login Systems)
+- How to handle passwords (never store them as plain text)
+- How long login sessions should last (15 minutes of inactivity)
+- Password requirements (minimum 8 characters)
+
+**API Bundle** (For Server Communication)
+- How to format responses (always include success: true/false)
+- How to handle errors (always include a trace ID)
+- How to name endpoints (/api/v1/users not /getUsers)
+
+### To See All Available Bundles:
+```
+jettypod standards bundles
+```
+
+### To Add a Bundle:
+```
+jettypod standards add auth
+```
+(This adds all authentication-related rules)
+
+**Popular bundles:**
+- `shadcn` - Standards for using shadcn/ui component library
+- `auth` - Authentication and security standards
+- `api` - API design and error handling
+- `database` - Database naming and query safety
+- `ui` - User interface consistency and styling
+
+**What happens when you add a bundle:**
+- JettyPod checks if you already have conflicting bundles
+- It adds all the standards from that bundle to your active list
+- It suggests other bundles that work well with it
+- Example: Adding "auth" might suggest adding "api" too
+- Your CLAUDE.md file automatically updates
+
+### To See What's Currently Active:
+```
+jettypod standards list
+```
+
+**What this shows you:**
+- All your active standards grouped by category (Core, API, UI, etc.)
+- The priority of each standard (critical, high, medium, low)
+- Total count of active standards
+- Which bundles you've added
+- What stage your project is at (empty, growing, production)
+
+---
+
+## The Different Modes
+
+JettyPod has different "modes" that change how strict Claude is:
+
+### Speed Mode 🚀
+**When to use:** You need something working in the next hour
+**What Claude does:**
+- Writes the simplest code that works
+- Skips tests
+- Uses shortcuts
+- Doesn't worry about perfect structure
+
+### Discovery Mode 🔍
+**When to use:** You're exploring different options
+**What Claude does:**
+- Shows you 3 different ways to do things
+- Explains trade-offs
+- Helps you decide what's best
+
+### Production Mode 🛡️
+**When to use:** This code is going to real users
+**What Claude does:**
+- Adds error handling everywhere
+- Writes tests
+- Includes security checks
+- Documents everything
+
+### To Switch Modes:
+```
+jettypod speed        # Quick and dirty
+jettypod discovery    # Show me options
+jettypod production   # Do it right
+```
+
+**What happens when you switch modes:**
+1. JettyPod updates your configuration to remember the new mode
+2. Your CLAUDE.md file is completely regenerated
+3. The same standards stay active, but they're presented differently:
+   - **Speed mode**: Claude sees condensed, minimal rules
+   - **Discovery mode**: Claude sees balanced detail with examples
+   - **Production mode**: Claude sees full documentation with all edge cases
+4. Claude's behavior immediately changes:
+   - Speed → Claude writes faster, simpler code
+   - Production → Claude adds error handling, tests, and documentation
+5. The mode stays active until you switch again
+
+---
+
+## Real-World Scenarios
+
+### Scenario 1: Starting a New Project
+
+You're building a new website from scratch.
+
+1. Create your project folder
+2. Run `jettypod standards init`
+3. JettyPod detects it's a website and adds appropriate rules
+4. Claude now knows to use React components, how to name them, where to put them
+
+### Scenario 2: Joining an Existing Team
+
+You just joined a team with their own coding standards.
+
+1. Your team lead exports their standards: `jettypod standards export team-rules.json`
+   - **What gets exported:**
+     - All active standards and their settings
+     - Which bundles are being used
+     - Any custom modifications
+     - The project stage (empty/growing/production)
+     - The current mode preference
+   - **What doesn't get exported:**
+     - Personal preferences
+     - History of changes
+     - Local file paths
+
+2. They share this file with you (via Git, Slack, email, etc.)
+
+3. You import it: `jettypod standards import team-rules.json`
+   - **What happens:**
+     - Your local standards are replaced with the team's
+     - Your CLAUDE.md regenerates to match
+     - You get the exact same setup as your team
+     - Your mode might change to match theirs
+
+4. Now Claude follows the same rules as everyone else
+   - Everyone's code looks consistent
+   - No more "why did you name it that way?" discussions
+   - New team members get up to speed instantly
+
+### Scenario 3: Switching Between Projects
+
+You work on Project A in the morning (startup, move fast) and Project B in the afternoon (bank, very careful).
+
+**Project A:**
+```
+cd project-a
+jettypod speed
+```
+Claude writes quick code with shortcuts
+
+**Project B:**
+```
+cd project-b
+jettypod production
+```
+Claude writes careful code with full testing
+
+### Scenario 4: Growing Project
+
+Your project starts small but grows over time.
+
+**Month 1:** Just you coding
+```
+jettypod standards stage empty
+```
+Only basic rules active
+
+**Month 3:** Small team
+```
+jettypod standards stage growing
+```
+More rules activate automatically
+
+**Month 12:** Large team, real users
+```
+jettypod standards stage production
+```
+All rules active, full standards
+
+### Scenario 5: Refreshing Claude's Knowledge
+
+Sometimes you need to refresh what Claude knows about your standards.
+
+**When to refresh CLAUDE.md:**
+- After adding or removing bundles
+- After changing project stage
+- If Claude seems confused about standards
+- After importing team standards
+
+**How to refresh:**
+```
+jettypod standards update
+```
+This regenerates the CLAUDE.md file with your current standards
+
+**Note:** Mode switches (speed/production/discovery) automatically refresh CLAUDE.md, so you don't need to run update after switching modes.
+
+---
+
+## How JettyPod Decides What Goes in CLAUDE.md
+
+This is the logic for what standards Claude actually sees:
+
+### Step 1: Bundle Addition
+When you add a bundle (like `jettypod standards add auth`), ALL standards from that bundle are added to your active list. No picking and choosing - you get the whole package.
+
+**Example**: The "auth" bundle includes:
+- Password handling rules
+- Session management rules
+- OAuth integration rules
+- Two-factor authentication rules
+- Security error handling rules
+- Form validation rules
+
+### Step 2: Stage Filtering
+Your project stage acts like a filter. Standards have stages too:
+- **Empty stage** (just starting) → Only see "beginner" standards
+- **Growing stage** (active development) → See beginner + intermediate standards  
+- **Production stage** (live users) → See ALL standards
+
+**Think of it like a video game:**
+- Level 1 player: Gets basic instructions
+- Level 50 player: Gets advanced strategies
+- The information exists, but you only see what's relevant to your level
+
+### Step 3: Mode Presentation
+The mode doesn't change WHAT standards exist, but HOW Claude sees them:
+
+**Speed Mode** (Time crunch):
+- Shows only "critical" and "high" priority standards
+- One-line descriptions
+- No examples
+- Result: 6-8 standards visible to Claude
+
+**Discovery Mode** (Exploring):
+- Shows all your active standards
+- Balanced descriptions
+- Some examples
+- Result: 11-15 standards visible to Claude
+
+**Production Mode** (Being careful):
+- Shows all your active standards
+- Full documentation
+- Detailed examples
+- Edge cases explained
+- Result: 30+ standards visible to Claude
+
+### The Complete Formula:
+```
+What Claude Sees = (Bundles You Added) 
+                   → Filtered by (Project Stage)
+                   → Formatted by (Current Mode)
+```
+
+**Example Scenario:**
+- You add: core + auth + api bundles (24 total standards)
+- Your stage: growing (filters out 6 advanced standards)
+- Your mode: speed (shows only 8 critical ones in condensed format)
+- Claude sees: 8 standards formatted as quick rules
+
+---
+
+## What Happens Behind the Scenes
+
+1. **When you add standards**, JettyPod creates a hidden folder (.jettypod) in your project
+   - **The folder structure:**
+     ```
+     .jettypod/
+     ├── standards/
+     │   ├── active.json (your current rules)
+     │   ├── custom.json (your modifications)
+     │   └── history.json (track of changes)
+     └── bundles.json (which bundles you've added)
+     ```
+
+2. **This folder contains:**
+   - **Your active rules** - A list of all standards currently turned on
+   - **Your custom modifications** - Any rules you've changed from the defaults
+   - **History of changes** - Last 20 changes you've made (in case you need to undo)
+
+3. **CLAUDE.md file** is created/updated - this is what Claude actually reads
+   - **How this works:**
+     - JettyPod takes all your active standards
+     - Combines them with your current mode (speed/production)
+     - Formats them in a way Claude understands
+     - Writes it all to CLAUDE.md in your project root
+     - Claude reads this file every time you start a conversation
+
+4. **When you switch modes**, the CLAUDE.md file regenerates with different formatting:
+   - **Speed mode:** Shows only critical rules (about 6-8 standards)
+   - **Discovery mode:** Shows moderate detail (about 11-15 standards)  
+   - **Production mode:** Shows everything in detail (30+ standards)
+   - **Why different amounts?**
+     - In speed mode, you don't want Claude overthinking
+     - In production mode, you want Claude to be thorough
+     - The same standards exist, but Claude only sees what's relevant
+
+---
+
+## Common Questions
+
+### "Why do I need this?"
+
+Without standards, every time you start a new conversation with Claude, you get different coding styles. One day variables are named `userId`, the next day `user_id`, the third day `userID`. This creates messy, inconsistent code.
+
+### "Can I customize the rules?"
+
+Yes! While we don't have a nice interface yet, you can:
+- Add or remove bundles
+- Create custom standards (coming soon in an easier way)
+- Export and share your customizations
+
+### "What if I don't like a rule?"
+
+For now, you add bundles as packages. In the future, you'll be able to:
+- Turn individual rules on/off
+- Modify specific rules
+- Create your own bundles
+
+### "Does this work with other AI assistants?"
+
+Currently, it's designed specifically for Claude. The CLAUDE.md file is formatted for Claude's understanding.
+
+---
+
+## What It Can't Do (Yet)
+
+### Current Limitations:
+
+1. **No Fine-Grained Control**
+   - You can't easily turn off just one rule from a bundle
+   - You take the whole bundle or nothing
+
+2. **No UI Interface**
+   - Everything is command-line based
+   - No visual way to browse or edit standards
+
+3. **No Validation**
+   - JettyPod doesn't check if your code follows the standards
+   - It only tells Claude what the standards are
+
+4. **No Team Sync**
+   - Changes don't automatically sync across team members
+   - You have to manually export/import
+
+5. **No Conflict Resolution**
+   - If two bundles have conflicting rules, it doesn't warn you clearly
+   - Both rules might be active, causing confusion
+
+6. **Limited Project Detection**
+   - Might not recognize all project types
+   - Defaults to basic standards if unsure
+
+7. **No Standard Suggestions**
+   - Doesn't analyze your existing code to suggest standards
+   - Doesn't learn from your preferences
+
+---
+
+## Future Vision
+
+### Coming Soon:
+- Visual interface for managing standards
+- Individual rule toggles
+- Team synchronization
+- Standard validation in your code
+- AI-powered standard suggestions
+
+### Later:
+- Industry-specific bundles (finance, healthcare, gaming)
+- Company-wide standard libraries
+- Integration with code review tools
+- Automatic code fixing to match standards
+
+---
+
+## Quick Reference
+
+### Essential Commands:
+
+| What You Want | Command |
+|--------------|---------|
+| Start using standards | `jettypod standards init` |
+| See available bundles | `jettypod standards bundles` |
+| Add more rules | `jettypod standards add [bundle]` |
+| See active rules | `jettypod standards list` |
+| Refresh CLAUDE.md file | `jettypod standards update` |
+| Work fast | `jettypod speed` |
+| Be careful | `jettypod production` |
+| Explore options | `jettypod discovery` |
+| Ask about JettyPod philosophy | `jettypod context "question"` |
+
+### Problem Solving:
+
+| Problem | Solution |
+|---------|----------|
+| "No standards showing" | Run `jettypod standards init` |
+| "Wrong mode active" | Run `jettypod [mode]` to switch |
+| "Need team standards" | Ask for their export file |
+| "Too many standards" | Switch to speed mode |
+| "Not enough standards" | Switch to production mode |
+
+---
+
+## The Bottom Line
+
+JettyPod Standards is like having a style guide that Claude actually reads and follows. Instead of telling Claude the same preferences over and over, you set them once and Claude remembers them for your entire project.
+
+It's not perfect yet - you can't customize everything, and some features are still being built. But it solves the biggest problem: keeping your code consistent when working with AI.
+
+The goal is simple: **Set your standards once, and Claude follows them every time.**