Skip to content

CONFIGURATION_SYSTEM.md

Latest commit

 

History

History
544 lines (380 loc) · 11.2 KB

CONFIGURATION_SYSTEM.md

File metadata and controls

544 lines (380 loc) · 11.2 KB

Configuration System Summary

Quick Start + Master Toggles + Simplified Rules

What We Built

A balanced, user-friendly configuration system that gives you two options:

  1. Quick Start (2 minutes) - Choose a preset, done
  2. Custom (5 minutes) - Granular control over every setting

The Problem We Solved

Before: Users had to toggle 100+ individual settings manually After: Choose a preset OR use master toggles + simplified categories

System Components

1. Quick Start Presets

Location: PROJECT_STARTER.md - Quick Start Configuration section

Users simply select their tech stack:

### Project Preset

- [ ] **Static Website** - HTML, Modern CSS, Vanilla JS
- [x] **Astro Site** - Astro 5, Modern CSS, Islands
- [ ] **React App** - React, TypeScript, Vite
- [ ] **Next.js App** - Next.js 15, App Router
- [ ] **Vue/Nuxt** - Vue 3, Nuxt, Composition API
- [ ] **SvelteKit** - Svelte 5, SvelteKit, Runes
- [ ] **Full Stack** - Complete backend + frontend + database
- [ ] **Custom** - Manual configuration

Run /quick-start and everything is configured automatically.

2. Master Toggles

Location: PROJECT_STARTER.md - Quick Start Configuration section

Bulk enable/disable entire feature categories:

### Master Toggles

- **MCP Servers**: `TRUE` # All database/cloud integrations
- **Development Hooks**: `TRUE` # All git hooks and automation
- **Code Quality Rules**: `TRUE` # All linting and standards
- **AI Agents**: `TRUE` # All specialized agents

When FALSE, the entire section is skipped during setup.

3. Simplified Code Rules

Location: PROJECT_STARTER.md - Code Rules Configuration section

Instead of 100+ toggles, organized into logical categories:

## Code Rules Configuration

### Language Standards

- **Modern JavaScript**: `TRUE`
- **TypeScript**: `FALSE`
- **Node.js**: `FALSE`
- **Python**: `FALSE`

### Framework Standards

- **Astro**: `TRUE`
- **React**: `FALSE`
- **Next.js**: `FALSE`
- **Vue/Nuxt**: `FALSE`
- **Svelte/SvelteKit**: `FALSE`

### CSS & Styling

- **Modern CSS**: `TRUE`
- **Tailwind CSS**: `FALSE`
- **Sass/SCSS**: `FALSE`

### Backend & API

- **Hono**: `TRUE`
- **Express/Fastify**: `FALSE`
- **REST API**: `FALSE`
- **GraphQL**: `FALSE`

### Quality & Testing

- **WCAG AA Accessibility**: `TRUE`
- **SEO Optimization**: `TRUE`
- **Performance**: `TRUE`
- **Security**: `TRUE`
- **Testing Standards**: `FALSE`

### Platform Standards

- **Cloudflare Workers**: `TRUE`
- **Vercel**: `FALSE`
- **PWA**: `TRUE`

Total: ~20 toggle categories instead of 100+ individual rules

File Structure

.claude/
├── config/
│   └── preset-definitions.json     # Preset configurations
├── commands/
│   ├── quick-start.md              # Quick Start command
│   ├── mcp-setup.md                # MCP configuration
│   ├── hooks-setup.md              # Hooks configuration
│   └── rules-setup.md              # Rules configuration (NEW)
└── rules/
    ├── definitions/                # Rule definitions library (FUTURE)
    │   ├── modern-javascript.json
    │   ├── astro-conventions.json
    │   ├── wcag-aa.json
    │   └── ...
    └── config.json                 # Generated rules config

docs/
└── guides/
    └── quick-start-guide.md        # Complete usage guide

PROJECT_STARTER.md                   # Updated with new sections

User Workflows

Workflow 1: Quick Start (Recommended)

Time: 2 minutes

# 1. Edit PROJECT_STARTER.md

### Project Preset

- [x] **Astro Site**
# 2. Run one command
/quick-start

Result:

  • Code rules for Astro + Modern CSS + JavaScript
  • MCP servers: GitHub, Cloudflare, Sentry, GA4
  • Development hooks: Pre-commit, auto-format, README sync
  • Project structure created
  • Dependencies suggested

Workflow 2: Quick Start with Overrides

Time: 3 minutes

# 1. Select preset

### Project Preset

- [x] **Astro Site**

# 2. Override specific settings

## Code Rules Configuration

- **TypeScript**: `TRUE` # Add TypeScript
- **Tailwind CSS**: `TRUE` # Add Tailwind
# 3. Apply with overrides
/quick-start

Workflow 3: Master Toggle Control

Time: 3 minutes

# 1. Select preset

### Project Preset

- [x] **React App**

# 2. Disable unwanted categories

### Master Toggles

- **MCP Servers**: `FALSE` # No external services
- **Development Hooks**: `TRUE` # Keep automation
- **Code Quality Rules**: `TRUE` # Keep linting
# 3. Apply
/quick-start

Result: React app with hooks and rules, but no MCP integrations

Workflow 4: Full Custom Control

Time: 5-10 minutes

# 1. Select custom preset

### Project Preset

- [x] **Custom**

# 2. Configure each section manually

### Master Toggles

- **MCP Servers**: `TRUE`
- **Development Hooks**: `TRUE`
- **Code Quality Rules**: `TRUE`

## Code Rules Configuration

- **Modern JavaScript**: `TRUE`
- **TypeScript**: `TRUE`
- **Astro**: `TRUE` (... configure all sections ...)

## MCP Configuration

- **Neon Database**: `TRUE`
- **Cloudflare**: `TRUE` (... configure all MCPs ...)

## Hooks Configuration

- **Pre-Commit Validation**: `TRUE`
- **Auto Format on Save**: `TRUE` (... configure all hooks ...)
# 3. Apply each section
/mcp-setup
/hooks-setup
/rules-setup

Commands

/quick-start

Purpose: Apply preset configuration Usage:

/quick-start              # Apply selected preset
/quick-start --validate   # Check config without applying
/quick-start --show-preset # Display what will be configured
/quick-start --reset      # Reset to custom mode

/mcp-setup

Purpose: Configure MCP servers Respects: MCP Servers master toggle

/hooks-setup

Purpose: Configure development hooks Respects: Development Hooks master toggle

/rules-setup (NEW)

Purpose: Configure code quality rules Respects: Code Quality Rules master toggle

Preset Definitions

Location: .claude/config/preset-definitions.json

Each preset includes:

{
  "astro-site": {
    "name": "Astro Site",
    "description": "Astro 5, Modern CSS, Islands Architecture",
    "rules": {
      "Modern JavaScript": true,
      "Astro": true,
      "Modern CSS": true,
      "WCAG AA Accessibility": true,
      "SEO Optimization": true,
      "Performance": true,
      "Security": true,
      "PWA": true,
      "Cloudflare Workers": true
    },
    "mcp": {
      "GitHub": true,
      "Cloudflare": true,
      "Sentry": true,
      "Google Analytics 4": true
    },
    "hooks": {
      "Pre-Commit Validation": true,
      "Commit Message Validation": true,
      "Auto Format on Save": true,
      "Auto Import Sort": true,
      "README Sync": true,
      "Task Completion Notifications": true,
      "Agent Error Handling": true
    }
  }
}

Benefits

For Beginners

  • No decision fatigue - Choose preset, done
  • Best practices included - Industry standards automatically applied
  • Learn by example - See what professionals use

For Experts

  • Speed - 2 minutes instead of 30-60 minutes
  • Consistency - Same setup across all projects
  • Flexibility - Override any preset setting

For Teams

  • Standardization - Everyone uses same configuration
  • Onboarding - New members select preset and start
  • Governance - Master toggles enforce policies

Key Features

1. Hierarchical Control

Master Toggle (FALSE)
  ↓
Entire category disabled
  ↓
Individual settings ignored

Example:

- **MCP Servers**: `FALSE` # Nothing below matters
- **Neon Database**: `TRUE` # Ignored
- **Cloudflare**: `TRUE` # Ignored

2. Preset Inheritance

Preset Selection
  ↓
Auto-populate all settings
  ↓
User can override
  ↓
Final configuration

3. Configuration Layers

1. Preset Defaults
2. Master Toggle Overrides
3. Section Overrides
4. Individual Setting Overrides

Most specific wins.

What Changed in PROJECT_STARTER.md

Added Sections

  1. Quick Start Configuration (Line ~167)

    • Project Preset selection
    • Master Toggles

  2. Code Rules Configuration (Line ~197)

    • Simplified categories
    • ~20 toggle groups instead of 100+

Modified Sections

  1. MCP Configuration (Line ~245)

    • Added "Optional" note
    • Only needed for Custom preset or overrides

  2. Hooks Configuration (Line ~344)

    • Added "Optional" note
    • Only needed for Custom preset or overrides

Examples

Example 1: Astro Site

### Project Preset

- [x] **Astro Site**

### Master Toggles

- **MCP Servers**: `TRUE`
- **Development Hooks**: `TRUE`
- **Code Quality Rules**: `TRUE`
- **AI Agents**: `TRUE`

Run /quick-start →

Configured:

  • Modern JavaScript + Astro + Modern CSS rules
  • GitHub + Cloudflare + Sentry + GA4 MCPs
  • Pre-commit, auto-format, README sync hooks
  • Astro-specific agents enabled

Example 2: Minimal Setup

### Project Preset

- [x] **Static Website**

### Master Toggles

- **MCP Servers**: `FALSE` # No external services
- **Development Hooks**: `TRUE` # Just automation
- **Code Quality Rules**: `TRUE` # Just linting
- **AI Agents**: `FALSE` # Core agents only

Run /quick-start →

Configured:

  • Modern JavaScript + Modern CSS rules
  • Pre-commit + auto-format hooks
  • No MCP integrations
  • No specialized agents

Example 3: Full Stack

### Project Preset

- [x] **Full Stack**

### Master Toggles

(all TRUE - use full preset)

Run /quick-start →

Configured:

  • JavaScript, TypeScript, Node.js, React, Next.js, Hono rules
  • Neon, Cloudflare, Vercel, Sentry, Stripe, GA4 MCPs
  • All quality hooks + security scanning
  • Full agent library

Next Steps for Users

After setup:

# 1. Environment variables
cp .env.example .env
# Add API keys

# 2. Install dependencies
npm install

# 3. Create project plan
/project-planner

# 4. Generate tasks
/task-planner

# 5. Start building
/task-runner

Implementation Status

✅ Completed

  • Quick Start section in PROJECT_STARTER.md
  • Master Toggles system
  • Simplified Code Rules Configuration
  • Preset definitions JSON
  • /quick-start command documentation
  • Quick Start Guide
  • Updated README.md
  • Configuration System Summary (this doc)

🔮 Future Implementation

  • /quick-start command execution logic
  • /rules-setup command execution logic
  • Rule definitions library (JSON files)
  • Preset validation logic
  • Configuration conflict detection
  • Auto-install dependencies based on preset

Summary

We created a balanced configuration system that:

✅ Reduces complexity - 100+ individual settings → 8 presets or 20 categories ✅ Saves time - 2 minutes with preset vs 30-60 minutes manual ✅ Maintains flexibility - Can override any preset setting ✅ Provides control - Master toggles for bulk operations ✅ Scales well - Works for simple to complex projects ✅ Teams friendly - Consistent setup across organization

The user gets:

  • Quick Start for speed
  • Master toggles for bulk control
  • Simplified rules for granular control
  • Full custom for unique needs

Best of all worlds: Simple by default, powerful when needed.