@djm204/agent-skills 1.0.0

package/templates/engineering/cli-tools/.cursor/rules/error-handling.mdc

@@ -0,0 +1,67 @@
+---
+description: Error Handling
+alwaysApply: false
+---
+
+# CLI Error Handling
+
+Patterns for handling errors gracefully and providing helpful feedback.
+
+## Exit Codes
+
+| Code | Meaning | Code | Meaning |
+|------|---------|------|---------|
+| 0 | Success | 2 | Invalid arguments |
+| 1 | General error | 126 | Cannot execute |
+| 64-78 | BSD sysexits | 130 | Interrupted (Ctrl+C) |
+
+Map error types to exit codes in a central handler:
+
+```go
+switch {
+case errors.Is(err, ErrInvalidArgs): os.Exit(2)
+case errors.Is(err, context.Canceled): os.Exit(130)
+default: os.Exit(1)
+}
+```
+
+## Error Message Structure
+
+Every error should include: **what happened**, **context** (paths, values), **why** (root cause), and **how to fix** (actionable suggestions).
+
+```
+Error: cannot read config file
+  File: ~/.config/mytool/config.yaml
+  Cause: permission denied
+Try:
+  • chmod 600 ~/.config/mytool/config.yaml
+```
+
+Implement as a structured `CLIError` type with `Message`, `Details`, `Cause`, and `Suggestions` fields.
+
+## Error Wrapping
+
+- Add context at each layer: `fmt.Errorf("deploy to %s: %w", env, err)`
+- Unwrap with `errors.Is` / `errors.As` for specific handling
+- Result chain: `"deploy to prod: invalid config: missing field 'api_key'"`
+
+## Graceful Degradation
+
+- **Partial failures**: Log warnings, continue processing, report summary (`failed 3/10 files`)
+- **Fallbacks**: Try env var → config file → default value
+- **Verbose mode**: Show stack traces and debug context only when `--verbose` / `--debug` is set
+
+## Anti-Patterns
+
+```go
+// Bad: Silent failure
+result, _ := riskyOp()
+
+// Good: Propagate with context
+result, err := riskyOp()
+if err != nil { return fmt.Errorf("risky op: %w", err) }
+```
+
+- **Generic messages** — `"operation failed"` is useless; include what, where, and how to fix
+- **Panic for recoverable errors** — return errors, never `panic` in CLI code
+- **String matching** — use `errors.Is(err, os.ErrNotExist)` not `err.Error() == "file not found"`

package/templates/engineering/cli-tools/.cursor/rules/overview.mdc

@@ -0,0 +1,58 @@
+---
+description: CLI Tools Development Overview
+alwaysApply: false
+---
+
+# CLI Tools Development Overview
+
+Guidelines for building professional command-line interfaces that are intuitive, robust, and maintainable.
+
+## Scope
+
+- Command-line applications and utilities
+- Developer tools, build systems, automation tooling
+- System administration scripts
+- Interactive terminal applications
+
+## Core Principles
+
+### Human-First Design
+- Helpful error messages that suggest fixes
+- Sensible defaults for common cases
+- Support both interactive and non-interactive modes
+- Follow platform conventions (POSIX, Windows)
+
+### Composability
+- Accept stdin, produce stdout; stderr for diagnostics
+- Support piping and redirection
+- Return meaningful exit codes
+
+### Predictability
+- Same inputs produce same outputs (deterministic)
+- Respect environment variables and config files
+- Never silently fail
+
+### Progressive Disclosure
+- Common operations require minimal arguments
+- Advanced features available but not required
+- Help text at multiple levels; examples for every command
+
+## Configuration Precedence
+
+1. Command-line flags (highest)
+2. Environment variables
+3. Local config file
+4. Global config file
+5. Default values (lowest)
+
+## Standard Flags
+
+Always support: `-h/--help`, `-v/--verbose`, `-q/--quiet`, `--version`, `--config`, `--no-color`, `--dry-run`, `-f/--force`
+
+## Definition of Done
+
+- [ ] All commands have help text, examples, and shell completions
+- [ ] Error messages suggest corrective actions; exit codes follow conventions
+- [ ] Works in non-interactive environments (CI/CD) and supports piping
+- [ ] Tests cover happy path and error cases
+- [ ] Installation and configuration precedence documented

package/templates/engineering/cli-tools/.cursor/rules/testing.mdc

@@ -0,0 +1,42 @@
+---
+description: CLI testing—unit (business logic), integration (full commands, capture stdout/stderr), exit codes. Mock I/O; test non-interactively.
+alwaysApply: false
+---
+
+# CLI Testing
+
+Guidelines for testing CLI applications.
+
+## Levels
+
+- **Unit**: Test business logic in isolation (functions that take config/inputs and return results). No CLI framework in unit tests; easy to assert and mock.
+- **Integration**: Run full commands (real or test binary); capture stdout, stderr, and exit code. Use temp dirs and env; no leftover state.
+- **E2E** (optional): Critical user flows with real binary; fewer, focused tests.
+
+## Structure for Testability
+
+- **Separate logic from CLI**: Core behavior in lib/ or core/ (pure functions or small modules); CLI layer only parses args, loads config, calls core, and prints. Unit test core; integration test CLI.
+- **Inject I/O**: Accept writer/reader or use package-level vars for stdout/stderr in tests so you can capture output without spawning process (or spawn and capture for integration).
+
+## Integration Tests
+
+- **Run command**: `exec` or language equivalent (e.g. `exec.Command` in Go, `child_process` in Node) with args; capture stdout, stderr, exit code.
+- **Assert**: Exit code (e.g. 0 success, 2 usage); stdout contains or equals expected; stderr empty or contains expected error.
+- **Environment**: Use temp dir for cwd and config; set env vars (e.g. `HOME`, `CONFIG`); clean up after.
+- **Non-interactive**: Set `--yes` or pipe to avoid prompts; or mock stdin with “y\n”.
+
+## Exit Codes
+
+- **Test explicitly**: Invalid args → 2; success → 0; runtime error → 1. Assert exit code in integration tests so contract is guaranteed.
+
+## Definition of Done (CLI Tests)
+
+- [ ] Unit tests for core logic; integration tests for main commands.
+- [ ] Exit codes and stdout/stderr asserted; tests run non-interactively in CI.
+- [ ] No reliance on real filesystem outside temp dirs; tests isolated.
+
+## Common Pitfalls
+
+- **Testing only happy path** - Test invalid args, missing files, and permission errors.
+- **Brittle output assertions** - Prefer “contains” or structured parse over exact string when output might change (e.g. version).
+- **Shared state** - Use temp dir per test; don’t rely on cwd or global config.

package/templates/engineering/cli-tools/.cursor/rules/user-experience.mdc

@@ -0,0 +1,43 @@
+---
+description: CLI UX—stdout vs stderr, output formats (table, JSON, plain), colors, progress, non-interactive. Human-first, scriptable.
+alwaysApply: false
+---
+
+# CLI User Experience
+
+Guidelines for clear, scriptable CLI output.
+
+## Streams
+
+- **stdout**: Data output only (for piping and scripts). JSON, table rows, or plain lines.
+- **stderr**: Progress, status, errors, logs. Never put parseable data on stderr when scripting is expected.
+- **Exit codes**: 0 success; 1 general error; 2 invalid usage. Document in help.
+
+## Output Formats
+
+- Support at least: **human** (table or formatted) and **machine** (JSON). Flag e.g. `--output json` or `-o json`. Default human; JSON for scripting.
+- **Table**: Align columns; consistent spacing. Optional `--no-headers` for scripts.
+- **JSON**: One object or one JSON line per result; no extra prose. Respect `--output json` in all commands that produce data.
+
+## Colors and Progress
+
+- **Colors**: Use for success (green), error (red), warning (yellow), info (blue). Respect `NO_COLOR` and `--no-color`; disable when stdout is not a TTY.
+- **Progress**: Spinner for indefinite; progress bar for known total. When not TTY (e.g. CI), print plain messages to stderr instead of spinner.
+- **Interactive**: Prompts only when stdin is TTY; support `--yes`/`--force` to skip confirmation in scripts.
+
+## Error Messages
+
+- **Structure**: What failed, context (path, value), cause if known, and suggested fix. Use stderr.
+- **Actionable**: “Cannot read config: permission denied at ~/.config/tool/config.yaml” and “chmod 600 ~/.config/tool/config.yaml”.
+
+## Definition of Done (CLI UX)
+
+- [ ] Data on stdout, progress/errors on stderr; exit codes documented.
+- [ ] JSON (or machine) output where scripting is needed; colors respect NO_COLOR/TTY.
+- [ ] Non-interactive mode (e.g. --yes) for CI; no hanging prompts.
+
+## Common Pitfalls
+
+- **Mixing data and logs on stdout** - Scripts break; keep data on stdout only.
+- **Always showing spinner** - In CI or pipe, show static message or nothing.
+- **Prompting without escape** - Provide flag to assume yes so automation doesn’t hang.

package/templates/engineering/cli-tools/CLAUDE.md

@@ -0,0 +1,356 @@
+# CLI Tools Development Guide
+
+Staff-level guidelines for building professional command-line interfaces that are intuitive, robust, and maintainable.
+
+---
+
+## Overview
+
+This guide applies to:
+
+- Command-line applications and utilities
+- Developer tools and build systems
+- System administration scripts
+- Automation and DevOps tooling
+- Interactive terminal applications
+
+### Key Principles
+
+1. **Human-First Design** - Intuitive for humans, scriptable for machines
+2. **Composability** - Do one thing well, compose with others
+3. **Predictability** - Consistent behavior, no surprises
+4. **Progressive Disclosure** - Simple things simple, complex things possible
+
+### Technology Stack
+
+| Language | Framework | Config | When to Use |
+|----------|-----------|--------|-------------|
+| Go | Cobra + Viper | Viper | Cross-platform binaries, performance |
+| Node.js | Commander.js | cosmiconfig | npm ecosystem, rapid development |
+| Python | Typer/Click | pydantic | Data processing, scripting |
+| Rust | Clap | config-rs | Performance-critical, systems tools |
+
+---
+
+## Command Structure
+
+### Root Command Pattern
+
+```go
+// Go with Cobra
+var rootCmd = &cobra.Command{
+    Use:   "mytool",
+    Short: "A brief description",
+    PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+        return initConfig()
+    },
+}
+
+func init() {
+    rootCmd.PersistentFlags().BoolP("verbose", "v", false, "verbose output")
+    rootCmd.PersistentFlags().String("config", "", "config file path")
+}
+```
+
+### Subcommands
+
+```bash
+mytool init          # Initialize project
+mytool build         # Build project
+mytool deploy        # Deploy to environment
+mytool config get    # Nested subcommand
+```
+
+### Configuration Precedence
+
+1. Command-line flags (highest)
+2. Environment variables
+3. Local config file
+4. Global config file
+5. Default values (lowest)
+
+---
+
+## Arguments and Flags
+
+### Standard Flags (Always Support)
+
+| Flag | Purpose |
+|------|---------|
+| `-h, --help` | Show help |
+| `-v, --verbose` | Verbose output |
+| `-q, --quiet` | Suppress output |
+| `--version` | Show version |
+| `--config` | Config file path |
+| `--no-color` | Disable colors |
+| `--dry-run` | Preview changes |
+| `-f, --force` | Skip confirmations |
+
+### Argument Validation
+
+```go
+// Go: Custom validation
+var runCmd = &cobra.Command{
+    Use:  "run <environment>",
+    Args: func(cmd *cobra.Command, args []string) error {
+        if len(args) != 1 {
+            return fmt.Errorf("requires exactly one argument")
+        }
+        validEnvs := []string{"dev", "staging", "prod"}
+        for _, env := range validEnvs {
+            if args[0] == env {
+                return nil
+            }
+        }
+        return fmt.Errorf("invalid environment %q", args[0])
+    },
+}
+```
+
+---
+
+## User Experience
+
+### Output Streams
+
+- **stdout**: Data output (for piping)
+- **stderr**: Progress, status, errors (for humans)
+
+```go
+// Correct stream usage
+fmt.Fprintln(os.Stderr, "Building...")  // Progress
+fmt.Println(result.Path)                 // Data output
+```
+
+### Colors
+
+| Color | Use For |
+|-------|---------|
+| Green | Success |
+| Red | Errors |
+| Yellow | Warnings |
+| Blue | Information |
+| Dim | Secondary info |
+
+Always respect `NO_COLOR` environment variable and `--no-color` flag.
+
+### Progress Indicators
+
+```go
+// Spinner for unknown duration
+spinner.Start()
+defer spinner.Stop()
+
+// Progress bar for known progress
+bar := progressbar.New(total)
+for _, item := range items {
+    process(item)
+    bar.Add(1)
+}
+```
+
+### Interactive Prompts
+
+```go
+// Confirmation with non-interactive fallback
+func confirm(message string, force bool) bool {
+    if force || !term.IsTerminal(int(os.Stdin.Fd())) {
+        return true
+    }
+    // Show interactive prompt
+}
+```
+
+---
+
+## Error Handling
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments |
+| 130 | Interrupted (Ctrl+C) |
+
+### Error Message Structure
+
+```
+Error: cannot read config file
+
+  File: /home/user/.config/mytool/config.yaml
+  Cause: permission denied
+
+Try:
+  • Check file permissions: ls -la ~/.config/mytool/
+  • Fix permissions: chmod 600 ~/.config/mytool/config.yaml
+```
+
+### Error Message Guidelines
+
+1. **What happened** - Clear description
+2. **Context** - Relevant details (paths, values)
+3. **Why** - Root cause if known
+4. **How to fix** - Actionable suggestions
+
+---
+
+## Testing
+
+### Test Levels
+
+| Level | What to Test | How |
+|-------|--------------|-----|
+| Unit | Business logic | Mock dependencies |
+| Integration | Full commands | Capture stdout/stderr |
+| E2E | User workflows | Run actual binary |
+
+### Mocking I/O
+
+```go
+// Capture output
+stdout := new(bytes.Buffer)
+stderr := new(bytes.Buffer)
+cmd.SetOut(stdout)
+cmd.SetErr(stderr)
+
+// Mock stdin
+r, w, _ := os.Pipe()
+go func() {
+    w.WriteString("y\n")
+    w.Close()
+}()
+os.Stdin = r
+```
+
+### Test Exit Codes
+
+```go
+func TestExitCodes(t *testing.T) {
+    cmd := exec.Command("./mytool", "invalid")
+    err := cmd.Run()
+    exitErr := err.(*exec.ExitError)
+    assert.Equal(t, 2, exitErr.ExitCode())
+}
+```
+
+---
+
+## Distribution
+
+### Version Information
+
+```bash
+$ mytool version
+mytool 1.0.0
+  commit: abc123
+  built:  2025-01-27
+  go:     go1.22
+```
+
+### Installation Methods
+
+```bash
+# Homebrew
+brew install myorg/tap/mytool
+
+# npm
+npm install -g mytool
+
+# Go
+go install github.com/myorg/mytool@latest
+
+# Direct download
+curl -fsSL https://example.com/install.sh | bash
+```
+
+### Shell Completions
+
+```bash
+# Generate completions
+mytool completion bash > /etc/bash_completion.d/mytool
+mytool completion zsh > "${fpath[1]}/_mytool"
+mytool completion fish > ~/.config/fish/completions/mytool.fish
+```
+
+---
+
+## Definition of Done
+
+A CLI tool is ready for release when:
+
+- [ ] All commands have help text and examples
+- [ ] Error messages suggest corrective actions
+- [ ] Exit codes follow conventions
+- [ ] Works in non-interactive environments (CI/CD)
+- [ ] Supports stdin/stdout piping
+- [ ] Configuration precedence documented
+- [ ] Shell completions available
+- [ ] Version flag shows useful info
+- [ ] Tests cover happy path and errors
+- [ ] Installation instructions documented
+
+---
+
+## Common Pitfalls
+
+### 1. Ignoring Non-TTY Environments
+
+```go
+// Bad: Always show spinner
+spinner.Start()
+
+// Good: Detect TTY
+if term.IsTerminal(int(os.Stderr.Fd())) {
+    spinner.Start()
+} else {
+    fmt.Fprintln(os.Stderr, "Processing...")
+}
+```
+
+### 2. Hardcoded Paths
+
+```go
+// Bad
+configPath := "/etc/mytool/config.yaml"
+
+// Good
+configPath := filepath.Join(xdg.ConfigHome, "mytool", "config.yaml")
+```
+
+### 3. Silent Failures
+
+```go
+// Bad
+result, _ := riskyOperation()
+
+// Good
+result, err := riskyOperation()
+if err != nil {
+    return fmt.Errorf("operation failed: %w", err)
+}
+```
+
+### 4. Missing Non-Interactive Support
+
+```go
+// Bad: Always prompts
+answer := prompt("Continue?")
+
+// Good: Respect --force flag
+if !force {
+    answer := prompt("Continue?")
+}
+```
+
+---
+
+## Resources
+
+- [Command Line Interface Guidelines](https://clig.dev/)
+- [Better CLI](https://better-cli.org/)
+- [Cobra Documentation](https://cobra.dev/)
+- [Commander.js](https://github.com/tj/commander.js)
+- [Click Documentation](https://click.palletsprojects.com/)
+- [Clap Documentation](https://docs.rs/clap/)

package/templates/engineering/data-engineering/.cursor/rules/data-modeling.mdc

@@ -0,0 +1,71 @@
+---
+description: Data Modeling
+alwaysApply: false
+---
+
+# Data Modeling
+
+Patterns for scalable, maintainable data models.
+
+## Medallion Architecture
+
+- **Bronze/Raw** — exact source copy, append-only, no transforms
+- **Silver/Curated** — validated, typed, deduplicated, business keys applied
+- **Gold/Marts** — aggregated, business-ready, optimized for consumption
+
+## Dimensional Modeling (Star Schema)
+
+- **Fact tables** — immutable events with measures and FK references to dimensions; partition by date
+- **Dimension tables** — descriptive attributes with surrogate keys for SCD support
+
+```sql
+-- Fact: measures + foreign keys, partitioned by date
+CREATE TABLE facts.orders (
+    order_id STRING, customer_key BIGINT, product_key BIGINT,
+    quantity INT, total_amount DECIMAL(12,2), _loaded_at TIMESTAMP
+) PARTITIONED BY (order_date);
+
+-- Dimension: surrogate key + SCD Type 2 tracking
+CREATE TABLE dims.customers (
+    customer_key BIGINT GENERATED ALWAYS AS IDENTITY,
+    customer_id STRING, name STRING, segment STRING,
+    effective_from DATE, effective_to DATE, is_current BOOLEAN
+);
+```
+
+## Slowly Changing Dimensions
+
+- **Type 1** — overwrite in place; no history
+- **Type 2** — close old row (`is_current=false`, set `effective_to`), insert new row; full history
+- **Type 3** — add `previous_*` column; limited history (one prior value)
+
+## Schema Design Rules
+
+- **Types**: IDs as STRING, money as DECIMAL, dates as DATE/TIMESTAMP, flags as BOOLEAN
+- **Naming**: tables plural snake_case, columns singular snake_case, FKs as `*_key`, booleans as `is_*`/`has_*`, timestamps as `*_at`, dates as `*_date`
+- **Avoid wide tables** — normalize into fact + dimension; join at query time
+
+```sql
+-- Bad: float for money, string for dates
+unit_price FLOAT, order_date STRING
+
+-- Good: precise types
+unit_price DECIMAL(10,2), order_date DATE
+```
+
+## Partitioning Strategies
+
+- **Time-based** — most common; partition by date for time-series data
+- **Categorical** — partition by high-cardinality enum (e.g., event_type)
+- Avoid over-partitioning; use clustering/bucketing for secondary access patterns
+
+## Alternative Approaches
+
+- **Data Vault** — Hub (business keys) + Link (relationships) + Satellite (attributes with history); for enterprise DWH
+- **One Big Table (OBT)** — fully denormalized for BI tools; fast reads but harder updates
+
+## Anti-Patterns
+
+- Floating-point types for monetary values
+- Storing dates as strings (breaks date math, inconsistent formats)
+- Over-partitioning on high-cardinality columns (millions of tiny files)