Developer Tools Builder

CLI DESIGN PRINCIPLES
======================

1. DISCOVERABILITY
   Every command should be findable without reading docs.
   - Consistent help output at every level (--help, -h)
   - Tab completion for commands, subcommands, and flags
   - Suggest correct command on typo: "Did you mean 'deploy'?"
   - Group related commands under subcommands

2. PROGRESSIVE DISCLOSURE
   Simple things should be simple; complex things should be possible.
   - Most common operation should be the shortest command
   - Sensible defaults for every flag
   - Power users can supersede with flags and config files
   - Interactive prompts for required inputs not provided

3. COMPOSABILITY
   Play well with other tools.
   - Respect stdin/stdout/stderr conventions
   - JSON output flag for machine parsing (--json or --output json)
   - Non-zero exit codes for failures
   - Quiet mode (--quiet) and verbose mode (--verbose)
   - Pipe-friendly output

4. SAFETY
   Protect users from mistakes.
   - Confirmation prompts for destructive actions
   - --dry-run flag for risky operations
   - Undo capability where possible
   - Clear warning messages before irreversible actions

COMMAND NAMING CONVENTIONS
===========================
Pattern: <tool> <noun> <verb> [options]

GOOD:
  mycli project create --name "myapp"
  mycli deploy start --env production
  mycli config set key value
  mycli logs tail --service api

BAD:
  mycli createProject myapp
  mycli start-deployment --environment=production
  mycli setConfig --key=foo --value=bar

SUBCOMMAND ORGANIZATION:
  mycli
  ├── auth
  │   ├── login
  │   ├── logout
  │   └── status
  ├── project
  │   ├── create
  │   ├── list
  │   ├── delete
  │   └── info
  ├── deploy
  │   ├── start
  │   ├── status
  │   ├── rollback
  │   └── logs
  └── config
      ├── get
      ├── set
      ├── list
      └── reset

FLAG CONVENTIONS:
  --verbose / -v     Increase output detail
  --quiet / -q       Suppress non-essential output
  --json             Machine-readable output
  --help / -h        Show help
  --version          Show version
  --dry-run          Preview without executing
  --force / -f       Skip confirmation prompts
  --config           Path to config file

OUTPUT FORMATTING
==================

HUMAN-READABLE OUTPUT:
  Use spinners for long operations:
    ⠋ Deploying to production...
    ✓ Deployed successfully (took 34s)

  Use tables for structured data:
    NAME        STATUS    CREATED
    api-prod    running   2024-01-15
    api-stage   stopped   2024-01-10

  Use colors meaningfully:
    Green:   Success, created, active
    Yellow:  Warning, pending, caution
    Red:     Error, deleted, failed
    Blue:    Info, links, identifiers
    Dim:     Secondary information

  Progress bars for multi-step operations:
    [████████████░░░░░░░░] 60% - Processing files...

MACHINE-READABLE OUTPUT (--json flag):
  {
    "status": "success",
    "data": { ... },
    "metadata": {
      "duration_ms": 340,
      "version": "1.2.3"
    }
  }

  Always include:
  - Consistent top-level structure
  - Error details in structured format
  - Pagination metadata if applicable

SDK DESIGN CHECKLIST
=====================

LANGUAGE IDIOMATICITY:
  [ ] Follows the conventions of each target language
  [ ] Uses native error handling patterns (exceptions, Result types, etc.)
  [ ] Naming follows language standards (camelCase in JS, snake_case in Python)
  [ ] Package manager distribution (npm, pip, gem, cargo, etc.)
  [ ] Uses language-native async patterns where applicable

INITIALIZATION:
  [ ] Minimum configuration to get started (API key only if possible)
  [ ] Constructor/factory pattern appropriate for the language
  [ ] Environment variable fallback for configuration
  [ ] Validation of configuration at initialization, not first call

  # Good initialization examples:
  # Python
  client = MySDK(api_key="...")

  # JavaScript
  const client = new MySDK({ apiKey: "..." });

  # Go
  client, err := mysdk.NewClient(mysdk.WithAPIKey("..."))

ERROR HANDLING:
  [ ] Typed/specific error classes (not generic exceptions)
  [ ] Error messages include: what happened, why, and how to fix
  [ ] Retry logic built in for transient failures
  [ ] Timeout configuration with sensible defaults
  [ ] Rate limit handling with automatic backoff

  # Good error example:
  class AuthenticationError(MySDKError):
      """API key is invalid or expired.
      Get a new key at [dashboard-endpoint]/keys"""

PAGINATION:
  [ ] Automatic pagination with iterator/generator pattern
  [ ] Manual pagination option for control
  [ ] Consistent across all list endpoints

  # Good pagination example (Python):
  for item in client.items.list():  # auto-paginates
      print(item.name)

LOGGING AND DEBUGGING:
  [ ] Debug mode shows HTTP requests/responses
  [ ] Uses the language's standard logging framework
  [ ] No sensitive data in logs (redact API keys, tokens)
  [ ] Request IDs in responses for support correlation

API DESIGN PRINCIPLES
======================

CONSISTENCY:
  - Consistent naming across all endpoints
  - Consistent response structure
  - Consistent error format
  - Consistent pagination pattern
  - Consistent authentication approach

RESOURCE NAMING:
  Good: /api/v1/users/{id}/projects
  Bad:  /api/v1/getUserProjects?userId=123

  Rules:
  - Use nouns, not verbs (HTTP methods provide the verb)
  - Use plural nouns (users, not user)
  - Use kebab-case for multi-word resources
  - Nest resources to show relationships (max 2-3 levels)

RESPONSE STRUCTURE:
  Success:
  {
    "data": { ... },
    "metadata": {
      "request_id": "req_abc123",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  }

  Error:
  {
    "error": {
      "code": "invalid_parameter",
      "message": "The 'email' field must be a valid email address",
      "param": "email",
      "doc_url": "[official documentation]"
    }
  }

VERSIONING:
  - URL prefix versioning: /api/v1/... (most common, clearest)
  - Increment major version only for breaking changes
  - Support at least 2 versions simultaneously
  - Provide migration guides for version upgrades
  - Deprecation warnings in response headers before sunset

RATE LIMITING:
  - Return rate limit info in response headers:
    X-RateLimit-Limit: 1000
    X-RateLimit-Remaining: 999
    X-RateLimit-Reset: 1705312200
  - Return 429 status with Retry-After header when exceeded
  - Document rate limits clearly

DOCUMENTATION HIERARCHY
=========================

TIER 1: GETTING STARTED (< 5 minutes to first success)
  - Quick start guide: Install, authenticate, make first call
  - Copy-pasteable code that works immediately
  - Result the developer sees after running the code
  Priority: This is the MOST IMPORTANT page. Update it weekly.

TIER 2: GUIDES (task-oriented)
  - Common use cases with full examples
  - Authentication guide
  - Error handling guide
  - Pagination guide
  - Webhook setup guide
  One guide per common workflow.

TIER 3: API REFERENCE (comprehensive)
  - Every endpoint documented
  - Request and response schemas
  - Example requests in 3+ languages
  - Try-it-out / interactive console
  Generated from OpenAPI spec where possible.

TIER 4: CONCEPTUAL DOCS
  - Architecture overview
  - Glossary of terms
  - Rate limiting explanation
  - Security model
  For developers who need deeper understanding.

TIER 5: CHANGELOG AND MIGRATION
  - Changelog for every release
  - Migration guides for breaking changes
  - Deprecation notices with timelines

DOCUMENTATION QUALITY CHECKLIST:
  [ ] Every code example has been tested and works
  [ ] Examples use realistic data (not foo/bar)
  [ ] Copy button on every code block
  [ ] Search works and returns relevant results
  [ ] Mobile-friendly layout
  [ ] Feedback mechanism ("Was this helpful?")
  [ ] Updated within 1 week of any API change

ERROR MESSAGE PRINCIPLES
==========================

EVERY ERROR MESSAGE SHOULD ANSWER:
  1. WHAT happened? (clear description of the error)
  2. WHY did it happen? (the cause)
  3. HOW to fix it? (actionable next step)

BAD ERROR MESSAGES:
  x "Error: invalid input"
  x "Something went wrong"
  x "Error code 4012"
  x "null pointer exception at line 342"

GOOD ERROR MESSAGES:
  ✓ "Authentication failed: API key 'sk_test_...' is expired.
     Generate a new key at [dashboard-endpoint]/keys"

  ✓ "Rate limit exceeded: 1000 requests per minute.
     Retry after 30 seconds. See [official documentation]"

  ✓ "Invalid parameter 'email': 'not-an-email' is not a valid
     email address. Expected format: user@domain.com"

CLI ERROR EXAMPLE:
  Error: Could not connect to database at localhost:5432

  Possible causes:
    1. PostgreSQL is not running (try: pg_isready)
    2. Wrong port (check DATABASE_URL in env-config)
    3. Firewall blocking connection

  For more help: mycli docs db-connection

ERROR CODE SYSTEM:
  Use structured error codes that are searchable:
  - AUTH_001: Invalid API key
  - AUTH_002: Expired API key
  - AUTH_003: Insufficient permissions
  - RATE_001: Rate limit exceeded
  - INPUT_001: Missing required field
  Each code should have a corresponding documentation page.

IDEAL DEVELOPER ONBOARDING JOURNEY
=====================================
Step 1: DISCOVERY (30 seconds)
  Developer lands on your site.
  They should understand WHAT your tool does immediately.
  Hero section: One sentence + live demo or code example.

Step 2: SIGNUP (60 seconds)
  Minimal friction signup.
  - GitHub/Google OAuth preferred (no new password)
  - API key visible immediately after signup
  - No sales call required for getting started

Step 3: FIRST SUCCESS (< 5 minutes)
  Install and run first command or API call.
  - Copy-paste installation command
  - Copy-paste first API call with their actual API key
  - See a real result (not just "OK")

Step 4: REAL USE CASE (< 30 minutes)
  Build something meaningful.
  - Guide through a common use case
  - Complete working example they can modify
  - Link to next steps and advanced features

Step 5: INTEGRATION (< 2 hours)
  Integrate into their actual project.
  - Framework-specific guides (Next.js, Django, Rails, etc.)
  - Environment configuration guidance
  - Production deployment checklist

ONBOARDING METRICS TO TRACK:
  Metric                        Target
  ------                        ------
  Time to signup                < 60 seconds
  Time to first API call        < 5 minutes
  Quickstart completion rate    > 60%
  Day 1 retention               > 40%
  Day 7 retention               > 25%
  Support tickets during setup  < 10% of new users

VERSIONING STRATEGY
=====================
Follow Semantic Versioning (SemVer): MAJOR.MINOR.PATCH

  MAJOR: Breaking changes (API contract changes)
  MINOR: New features, backward compatible
  PATCH: Bug fixes, backward compatible

CHANGELOG FORMAT (Keep a Changelog convention):
  ## [1.2.0] - 2024-01-15
  ### Added
  - New `projects.archive()` method
  - Support for webhook signature verification

  ### Changed
  - Improved error messages for authentication failures

  ### Fixed
  - Fixed pagination bug when total items is zero

  ### Deprecated
  - `projects.remove()` deprecated in favor of `projects.delete()`

RELEASE CHECKLIST:
  [ ] All tests pass
  [ ] Changelog updated
  [ ] Version bumped in package manifest
  [ ] Documentation updated for new/changed features
  [ ] Migration guide written (if breaking changes)
  [ ] Deprecation notices added (if applicable)
  [ ] SDK updates published for all supported languages
  [ ] Announcement posted (blog, changelog, social)