Initial commit

skills/spec-author/templates/configuration-schema.md

@@ -0,0 +1,274 @@
+# Configuration Schema: <!-- TODO: Feature Name -->
+
+**Document ID:** `config-[project]-[feature-number]-[slug]`
+**Created:** <!-- TODO: YYYY-MM-DD -->
+**Status:** <!-- TODO: Draft | Active | Deprecated -->
+**Owner:** <!-- TODO: Team/Individual -->
+
+---
+
+## Overview
+
+### Purpose
+<!-- TODO: Brief description of what this configuration controls -->
+
+### Scope
+<!-- TODO: Which components/services use this configuration -->
+
+### Configuration Files
+<!-- TODO: List configuration files and their locations, e.g.:
+- **Primary:** `config/[environment].yml`
+- **Overrides:** `config/local.yml` (git-ignored)
+- **Secrets:** Environment variables or vault
+-->
+
+### Precedence Order
+<!-- TODO: How configuration sources are merged, highest priority first, e.g.:
+1. Environment variables
+2. Local overrides (`config/local.yml`)
+3. Environment-specific (`config/production.yml`, `config/development.yml`)
+4. Base defaults (`config/default.yml`)
+-->
+
+---
+
+## Configuration Structure
+
+### File Organization
+<!-- TODO: Document configuration file structure using YAML or JSON format example -->
+
+---
+
+## Common Settings
+
+### Server Configuration
+<!-- TODO: Document server configuration settings with examples, e.g.:
+```yaml
+server:
+  host: localhost
+  port: 3000
+  timeout: 30000  # milliseconds
+```
+
+**Key Settings:**
+- `host`: Server bind address
+- `port`: Server port number
+-->
+
+### Database Configuration
+<!-- TODO: Document database configuration settings with examples, e.g.:
+```yaml
+database:
+  adapter: postgresql
+  host: localhost
+  port: 5432
+  name: app_development
+  username: dbuser
+  password: ${DB_PASSWORD}  # Use env var
+```
+
+**Key Settings:**
+- `adapter`: Database type
+- `pool.max`: Maximum database connections
+-->
+
+### Cache Configuration
+<!-- TODO: OPTIONAL - Remove if not applicable. Document cache configuration:
+```yaml
+cache:
+  adapter: redis
+  host: localhost
+  port: 6379
+  ttl: 3600  # seconds
+```
+-->
+
+### Logging Configuration
+<!-- TODO: Document logging configuration settings with examples, e.g.:
+```yaml
+logging:
+  level: info  # debug, info, warn, error
+  format: json  # json, text
+  outputs:
+    - type: console
+    - type: file
+      path: logs/app.log
+```
+
+**Key Settings:**
+- `level`: Minimum log level to output
+- `format`: Log output format
+-->
+
+### Security Configuration
+<!-- TODO: Document security configuration settings with examples, e.g.:
+```yaml
+security:
+  jwt:
+    secret: ${JWT_SECRET}  # Use env var
+    expiry: 3600  # seconds
+  cors:
+    enabled: true
+    allowed_origins:
+      - "http://localhost:3000"
+```
+
+**Key Settings:**
+- Document important security settings
+-->
+
+---
+
+## Required vs Optional
+
+### Required Configuration
+<!-- TODO: Document configuration that MUST be set for the application to start
+
+**Environment Variables:**
+```bash
+# Required in all environments
+DB_PASSWORD=<database-password>
+JWT_SECRET=<jwt-signing-secret>
+```
+
+**Validation Rules:**
+- List validation rules
+-->
+
+### Optional Configuration
+<!-- TODO: Document configuration with sensible defaults
+
+**Settings with Defaults:**
+- `setting.name`: Defaults to value
+-->
+
+---
+
+## Feature Flags
+
+<!-- TODO: OPTIONAL - Remove if not applicable. Document feature flags:
+```yaml
+features:
+  new_feature:
+    enabled: false
+    rollout_percentage: 0  # 0-100
+
+  experimental_feature:
+    enabled: false
+    environments:
+      - development
+      - staging
+```
+
+**Feature Flag Guidelines:**
+- Default to `false` for new features
+- Use `rollout_percentage` for gradual rollout
+-->
+
+---
+
+## Configuration Examples
+
+### Development Environment
+<!-- TODO: Document development environment configuration example:
+```yaml
+# config/development.yml
+server:
+  host: localhost
+  port: 3000
+
+database:
+  adapter: postgresql
+  host: localhost
+  port: 5432
+  name: app_development
+```
+-->
+
+### Production Environment
+<!-- TODO: Document production environment configuration example:
+```yaml
+# config/production.yml
+server:
+  host: 0.0.0.0
+  port: 8080
+
+database:
+  adapter: postgresql
+  host: db.production.internal
+  port: 5432
+  name: app_production
+```
+-->
+
+---
+
+## Configuration Validation
+
+### Startup Validation
+<!-- TODO: Document checks performed when application starts
+
+**Validation Steps:**
+1. Required environment variables are set
+2. Configuration files are valid YAML/JSON
+3. Database connection is successful
+4. Port is available
+
+**Failure Behavior:**
+- Application fails to start if validation fails
+- Error messages indicate which configuration is invalid
+-->
+
+### Runtime Validation
+<!-- TODO: OPTIONAL - Remove if not applicable. Document checks performed during operation
+
+**Health Checks:**
+- Database connection pool health
+- Cache connectivity
+
+**Monitoring Alerts:**
+- Connection pool exhaustion
+- Cache miss rate exceeds threshold
+-->
+
+---
+
+## Environment Variables Reference
+
+<!-- TODO: Document all environment variables:
+```bash
+# Database
+DB_PASSWORD=<required>
+
+# Security
+JWT_SECRET=<required-min-32-chars>
+API_KEY=<optional>
+
+# External Services
+REDIS_URL=<optional-defaults-to-config>
+```
+-->
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+<!-- TODO: Document common configuration issues and solutions
+
+**Application won't start:**
+- Check required environment variables are set
+- Verify database connection settings
+- Ensure port is not already in use
+
+**Performance issues:**
+- Review database pool settings
+- Check cache hit rate and TTL settings
+- Verify logging level is not set to `debug` in production
+
+**Configuration not taking effect:**
+- Check configuration precedence order
+- Verify environment variable names match exactly
+- Restart application after config changes
+-->