@geraldmaron/construct 1.0.0

package/skills/architecture/caching.md

@@ -0,0 +1,101 @@
+<!--
+skills/architecture/caching.md — Caching — Use this skill when designing caching strategies for applications, APIs, or infr
+
+Use this skill when designing caching strategies for applications, APIs, or infrastructure. ## Cache Layers
+-->
+# Caching
+
+Use this skill when designing caching strategies for applications, APIs, or infrastructure.
+
+## Cache Layers
+
+| Layer | Tool | Latency | Use Case |
+|---|---|---|---|
+| In-process | HashMap, LRU cache | <1ms | Hot config, computed values |
+| Distributed | Redis, Memcached | 1-5ms | Session data, query results |
+| CDN | Cloudflare, CloudFront | 10-50ms | Static assets, public API responses |
+| Browser | Cache-Control headers | 0ms | Assets, API responses for single user |
+
+## Cache Strategies
+
+### Cache-Aside (Lazy Loading)
+1. Check cache. If hit, return.
+2. If miss, read from database.
+3. Write result to cache with TTL.
+- Best for: read-heavy workloads with tolerant staleness
+- Risk: thundering herd on cache miss for hot keys
+
+### Write-Through
+1. Write to cache and database simultaneously.
+- Best for: data that must be fresh immediately after write
+- Risk: higher write latency
+
+### Write-Behind (Write-Back)
+1. Write to cache immediately.
+2. Asynchronously flush to database.
+- Best for: high write throughput with acceptable durability risk
+- Risk: data loss if cache fails before flush
+
+### Read-Through
+1. Cache itself fetches from database on miss.
+- Best for: simplifying application code
+- Requires a cache library that supports origin fetch
+
+## Cache Invalidation
+
+- **TTL-based**: set expiry on every key; simplest, but data can be stale up to TTL
+- **Event-based**: invalidate on write events; lowest staleness, requires pub/sub
+- **Version-based**: include version in cache key; new version = automatic miss
+- **Tag-based**: group related keys by tag; invalidate all keys with a tag at once
+
+### Thundering Herd Mitigation
+- Lock on miss: only one request fetches, others wait
+- Stale-while-revalidate: serve stale data while background refresh runs
+- Early expiry jitter: randomize TTL to avoid synchronized expiry
+
+## Redis Patterns
+
+- Use appropriate data structures: strings for simple values, hashes for objects, sorted sets for leaderboards
+- Set `maxmemory-policy` to `allkeys-lru` or `volatile-lru`
+- Use pipelining for batch operations
+- Monitor hit rate: target >90% for hot paths
+- Use Redis Cluster for horizontal scaling
+- Avoid large keys (>1MB) and hot keys (>10K ops/sec on single key)
+
+## CDN Configuration
+
+- Cache static assets with long TTL (1 year) and content-hash filenames
+- Cache public API responses with short TTL (30-300s)
+- Use `Vary` header correctly for content negotiation
+- Purge on deploy for assets without content hashing
+- Use edge functions for personalization at the CDN layer
+
+## HTTP Cache Headers
+
+```
+Cache-Control: public, max-age=31536000, immutable    # hashed assets
+Cache-Control: private, no-cache                       # user-specific
+Cache-Control: public, s-maxage=60, stale-while-revalidate=300
+ETag: "abc123"                                         # conditional requests
+```
+
+- `no-cache` means revalidate, not no caching
+- `no-store` means truly do not cache
+- Use `ETag` + `If-None-Match` for conditional requests
+
+## Monitoring
+
+- Cache hit rate per key prefix
+- Eviction rate and memory usage
+- Latency percentiles: p50, p95, p99
+- Cache size growth over time
+- Staleness: time between data change and cache update
+- Alert on hit rate drop below threshold (e.g., <80%)
+
+## Anti-Patterns
+
+- Caching without TTL (unbounded growth)
+- Caching errors or empty results without short TTL
+- Cache key collisions from insufficient namespacing
+- Serializing large objects when only a field is needed
+- Using cache as primary data store without durability plan

package/skills/architecture/cloud-native.md

@@ -0,0 +1,97 @@
+<!--
+skills/architecture/cloud-native.md — Cloud-Native Architecture — Use this skill when designing containerized, orchestrated, or microservice-based
+
+Use this skill when designing containerized, orchestrated, or microservice-based systems. ## Container Best Practices
+-->
+# Cloud-Native Architecture
+
+Use this skill when designing containerized, orchestrated, or microservice-based systems.
+
+## Container Best Practices
+
+- One process per container
+- Use multi-stage builds to minimize image size
+- Pin base image versions with digest, not just tag
+- Run as non-root user
+- No secrets in image layers; use runtime injection
+- Health check endpoint in every container
+- Graceful shutdown: handle SIGTERM, drain connections, exit cleanly
+
+## Kubernetes Patterns
+
+### Resource Management
+- Set CPU and memory requests and limits on every pod
+- Use Horizontal Pod Autoscaler based on CPU, memory, or custom metrics
+- Use PodDisruptionBudget to maintain availability during rollouts
+- Namespace per environment or team
+
+### Networking
+- Use Services for internal communication
+- Use Ingress or Gateway API for external traffic
+- NetworkPolicy to restrict pod-to-pod communication
+- DNS-based service discovery within the cluster
+
+### Configuration
+- ConfigMaps for non-sensitive configuration
+- Secrets for sensitive values (encrypted at rest with KMS)
+- Environment variables or volume mounts, not baked into images
+- External config: Vault, AWS Secrets Manager, or equivalent
+
+### Deployment Strategies
+- Rolling update: default, zero-downtime with readiness probes
+- Blue-green: instant switchover, requires double capacity
+- Canary: gradual traffic shift, best for risk-sensitive changes
+- Use readiness and liveness probes; do not conflate them
+
+## Microservice Design
+
+### Boundaries
+- One service per bounded context
+- Services own their data; no shared databases
+- Communicate via APIs or events, never direct database access
+- Keep services independently deployable
+
+### Communication
+- Synchronous: REST or gRPC for request-response
+- Asynchronous: message queues for events and commands
+- Use circuit breakers for synchronous calls (Hystrix pattern)
+- Set timeouts and retries with exponential backoff and jitter
+- Implement idempotency keys for retry-safe operations
+
+### Data Management
+- Database per service
+- Saga pattern for distributed transactions
+- Event sourcing when audit trail matters
+- CQRS when read and write patterns diverge significantly
+- Eventual consistency is acceptable for most cross-service data
+
+## Service Mesh
+
+- Sidecar proxy (Envoy, Linkerd) for mTLS, observability, traffic control
+- Retry, timeout, and circuit breaker policies in mesh config
+- Traffic splitting for canary deployments
+- Distributed tracing via mesh-injected headers
+- Evaluate mesh overhead; not every system needs one
+
+## Twelve-Factor Compliance
+
+1. Codebase: one repo per service
+2. Dependencies: explicitly declared and isolated
+3. Config: stored in environment, not code
+4. Backing services: attached resources via config
+5. Build/release/run: strict separation
+6. Processes: stateless; persist state in backing services
+7. Port binding: self-contained, export via port
+8. Concurrency: scale via process model
+9. Disposability: fast startup, graceful shutdown
+10. Dev/prod parity: keep environments as similar as possible
+11. Logs: emit to stdout, aggregate externally
+12. Admin processes: run as one-off tasks
+
+## Resilience Patterns
+
+- Retry with exponential backoff and jitter
+- Circuit breaker: open after N failures, half-open after cooldown
+- Bulkhead: isolate failures to prevent cascade
+- Timeout: every external call has a deadline
+- Fallback: degrade gracefully when dependencies are unavailable

package/skills/architecture/message-queue.md

@@ -0,0 +1,100 @@
+<!--
+skills/architecture/message-queue.md — Message Queues and Event-Driven Architecture — Use this skill when designing asynchronous communication, event-driven systems,
+
+Use this skill when designing asynchronous communication, event-driven systems, or message-based integrations. ## When to Use Message Queues
+-->
+# Message Queues and Event-Driven Architecture
+
+Use this skill when designing asynchronous communication, event-driven systems, or message-based integrations.
+
+## When to Use Message Queues
+
+- Decouple producers from consumers
+- Buffer spikes in traffic or processing load
+- Enable async processing of long-running tasks
+- Fan out events to multiple consumers
+- Guarantee delivery when consumers may be temporarily unavailable
+
+## Messaging Patterns
+
+### Point-to-Point (Queue)
+- One producer, one consumer per message
+- Work distribution across multiple consumer instances
+- Use for: task queues, job processing, command dispatch
+
+### Publish-Subscribe (Topic)
+- One producer, many consumers per message
+- Each subscriber gets a copy
+- Use for: event notification, real-time updates, audit logging
+
+### Request-Reply
+- Producer sends a message with a reply-to address
+- Consumer processes and responds
+- Use for: async RPC, distributed computation
+- Include correlation ID for matching responses
+
+## Technology Selection
+
+| System | Strength | Best For |
+|---|---|---|
+| Kafka | High throughput, replay, ordering | Event streaming, log aggregation, CDC |
+| RabbitMQ | Flexible routing, low latency | Task queues, RPC, complex routing |
+| SQS | Managed, simple, scales to zero | AWS-native task queues |
+| NATS | Ultra-low latency, lightweight | Microservice communication |
+| Pulsar | Multi-tenancy, tiered storage | Large-scale streaming |
+
+## Message Design
+
+- Include: event type, timestamp, correlation ID, source, schema version, payload
+- Use a schema registry for payload evolution (Avro, Protobuf, JSON Schema)
+- Keep messages self-contained; avoid requiring lookups to interpret
+- Small messages (<1MB); use references for large blobs
+- Version schemas; consumers must handle unknown fields gracefully
+
+## Delivery Guarantees
+
+### At-Most-Once
+- Fire and forget; fastest but may lose messages
+- Use for: metrics, non-critical notifications
+
+### At-Least-Once
+- Retry until acknowledged; may duplicate
+- Consumers must be idempotent
+- Use for: most business events
+
+### Exactly-Once
+- Requires idempotent consumers or transactional outbox
+- Expensive; only when business rules demand it
+- Use for: financial transactions, inventory updates
+
+## Ordering
+
+- Kafka: ordered within a partition; use partition key for related events
+- RabbitMQ: ordered within a single queue with one consumer
+- SQS FIFO: ordered by message group ID
+- Design consumers to tolerate out-of-order delivery when possible
+
+## Error Handling
+
+- Dead letter queue (DLQ) for messages that fail after max retries
+- Exponential backoff between retries
+- Poison message detection: log and skip after threshold
+- Monitor DLQ depth; alert when non-empty
+- Provide tooling to replay or reprocess DLQ messages
+
+## Transactional Outbox Pattern
+
+1. Write business data and outbox event in a single database transaction
+2. Background process polls outbox and publishes to message broker
+3. Mark outbox entry as published after broker acknowledgment
+- Guarantees event publication if database write succeeds
+- Alternative: change data capture (CDC) from the database log
+
+## Monitoring
+
+- Queue depth and age of oldest message
+- Consumer lag (Kafka: offset lag per partition)
+- Message throughput: produced, consumed, failed per minute
+- DLQ depth and growth rate
+- Consumer processing latency percentiles
+- Alert on: growing lag, DLQ growth, consumer crash loops

package/skills/architecture/security-arch.md

@@ -0,0 +1,105 @@
+<!--
+skills/architecture/security-arch.md — Security Architecture — Use this skill when designing authentication, authorization, network security, o
+
+Use this skill when designing authentication, authorization, network security, or zero-trust architectures. ## Zero Trust Principles
+-->
+# Security Architecture
+
+Use this skill when designing authentication, authorization, network security, or zero-trust architectures.
+
+## Zero Trust Principles
+
+- Never trust, always verify: authenticate and authorize every request
+- Least privilege: grant minimum permissions required for the task
+- Assume breach: design as if the perimeter is already compromised
+- Verify explicitly: use identity, device health, location, and behavior signals
+- Micro-segmentation: limit blast radius of any single compromise
+
+## Identity and Access Management
+
+### Authentication
+- Centralize authentication in an identity provider (IdP)
+- Support MFA for all human users; enforce for privileged accounts
+- Use short-lived tokens (15-60 min) with refresh token rotation
+- Machine-to-machine: mTLS or signed JWTs with narrow scopes
+- Federate identity across services; avoid per-service credential stores
+
+### Authorization
+- RBAC for coarse-grained access (admin, editor, viewer)
+- ABAC for fine-grained policies (resource owner, department, time)
+- Policy-as-code: OPA/Rego, Cedar, or equivalent
+- Evaluate authorization server-side on every request
+- Audit all access decisions; log denials prominently
+
+### OAuth 2.0 / OIDC
+- Use Authorization Code flow with PKCE for web and mobile
+- Client Credentials for service-to-service
+- Validate tokens server-side; do not trust client-side token claims
+- Rotate client secrets regularly
+- Restrict redirect URIs to exact match
+
+## Network Security
+
+### Segmentation
+- Separate trust zones: public, DMZ, internal, sensitive data
+- Network policies restrict traffic between zones
+- Service-to-service communication over mTLS
+- Egress filtering: allowlist outbound destinations
+
+### API Gateway
+- Centralize authentication, rate limiting, and logging
+- Terminate TLS at the gateway
+- Input validation and request size limits at the edge
+- IP allowlisting for admin and internal APIs
+
+### DNS Security
+- DNSSEC for domain integrity
+- DNS-over-HTTPS or DNS-over-TLS for privacy
+- Monitor for subdomain takeover on deprovisioned infrastructure
+
+## Data Protection
+
+### Encryption
+- TLS 1.2+ for all data in transit
+- AES-256-GCM or ChaCha20-Poly1305 for data at rest
+- Key management via HSM or cloud KMS; never store keys alongside data
+- Rotate encryption keys on a schedule and on suspected compromise
+- Envelope encryption for large data volumes
+
+### Classification
+- Public: no restrictions
+- Internal: accessible to authenticated employees
+- Confidential: restricted to authorized roles
+- Restricted: PII, financial, health data; strongest controls
+
+### Data Lifecycle
+- Retention policies defined per data class
+- Automated deletion at end of retention period
+- Secure deletion: cryptographic erasure or verified overwrite
+- Backup encryption with separately managed keys
+
+## Secrets Management
+
+- Use a dedicated secrets manager (Vault, AWS Secrets Manager, etc.)
+- Inject secrets at runtime, never at build time
+- Audit secret access with who, when, and from where
+- Rotate secrets on schedule and immediately on suspected exposure
+- Detect and alert on secret sprawl (secrets in repos, configs, logs)
+
+## Defense in Depth
+
+Layer controls so that no single failure compromises the system:
+
+1. **Perimeter**: WAF, DDoS protection, edge rate limiting
+2. **Network**: segmentation, firewall rules, mTLS
+3. **Application**: input validation, output encoding, auth checks
+4. **Data**: encryption, access control, audit logging
+5. **Monitoring**: anomaly detection, alerting, incident response
+
+## Compliance Considerations
+
+- Map controls to relevant frameworks: SOC 2, ISO 27001, PCI-DSS, HIPAA
+- Maintain evidence of control effectiveness
+- Automate compliance checks where possible
+- Review and update controls quarterly
+- Document accepted risks with business justification and owner

package/skills/development/cpp.md

@@ -0,0 +1,127 @@
+<!--
+skills/development/cpp.md — C/C++ Best Practices — Use this skill when writing, reviewing, or debugging C or C++ code.
+
+Use this skill when writing, reviewing, or debugging C or C++ code. ## Project Structure
+-->
+# C/C++ Best Practices
+
+Use this skill when writing, reviewing, or debugging C or C++ code.
+
+## Project Structure
+
+```
+include/
+  project/
+    module.h
+src/
+  module.cpp
+  main.cpp
+tests/
+  test_module.cpp
+CMakeLists.txt
+```
+
+- Separate headers (public API) from implementation
+- CMake as the build system; `CMakeLists.txt` per directory
+- Keep header dependencies minimal; forward-declare when possible
+- One class or module per header/source pair
+
+## Tooling
+
+| Tool | Purpose |
+|---|---|
+| clang-format | Formatting |
+| clang-tidy | Static analysis and modernization |
+| AddressSanitizer (ASan) | Memory error detection |
+| UndefinedBehaviorSanitizer (UBSan) | Undefined behavior detection |
+| Valgrind | Memory leak detection |
+| GoogleTest / Catch2 | Testing |
+| gcov / llvm-cov | Coverage |
+| cppcheck | Additional static analysis |
+
+## Modern C++ (C++17/20/23)
+
+- `std::string_view` over `const std::string&` for read-only string parameters
+- `std::optional<T>` for values that may be absent
+- `std::variant` for type-safe unions
+- Structured bindings: `auto [key, value] = pair;`
+- `if constexpr` for compile-time branching
+- `std::span` for non-owning views of contiguous data
+- Range-based for loops; `<ranges>` for composable transformations
+
+## Memory Management
+
+### RAII (Resource Acquisition Is Initialization)
+- Every resource (memory, file handle, lock, socket) owned by an object
+- Acquisition in constructor; release in destructor
+- No manual `new`/`delete` in application code
+
+### Smart Pointers
+- `std::unique_ptr`: single ownership, zero overhead
+- `std::shared_ptr`: shared ownership when genuinely needed (rare)
+- `std::weak_ptr`: breaking cycles in shared ownership
+- Raw pointers only for non-owning observation; never manage lifetime
+
+### Containers
+- `std::vector` as the default container
+- `std::array` for fixed-size collections
+- `std::unordered_map` for fast lookup; `std::map` when order matters
+- Reserve capacity when the size is known: `vec.reserve(n)`
+
+## Error Handling
+
+- Exceptions for C++: throw on failure, catch at boundaries
+- `std::expected<T, E>` (C++23) or equivalent library for value-or-error returns
+- `noexcept` on functions that do not throw (move constructors, destructors)
+- Never throw from destructors
+- C: return error codes; check every return value; use `errno` correctly
+
+## Concurrency
+
+- `std::thread` with `std::jthread` (C++20) for automatic join
+- `std::mutex` and `std::lock_guard` / `std::scoped_lock` for synchronization
+- `std::atomic` for lock-free operations on simple types
+- `std::async` and `std::future` for task-based parallelism
+- Avoid data races: either protect with mutex or use atomics
+- Thread sanitizer (`-fsanitize=thread`) in CI
+
+## Testing
+
+- GoogleTest or Catch2 for unit and integration tests
+- `TEST` macros for test definition; `EXPECT_*` / `REQUIRE` for assertions
+- CTest for test orchestration via CMake
+- Run with sanitizers enabled in CI
+- Fuzz testing with libFuzzer or AFL++ for input-handling code
+
+## Performance
+
+- Profile first: `perf`, `Instruments`, `VTune`
+- Minimize allocations: stack allocation > pool allocation > heap allocation
+- Cache-friendly data layout: struct-of-arrays over array-of-structs when iterating
+- Avoid virtual dispatch in hot paths when static polymorphism suffices (CRTP)
+- `constexpr` for compile-time computation
+- Link-time optimization (`-flto`) for cross-unit inlining
+
+## Build System
+
+- CMake with modern targets: `target_link_libraries`, `target_include_directories`
+- Compile with warnings: `-Wall -Wextra -Wpedantic -Werror`
+- Enable sanitizers in debug/CI builds
+- Use `FetchContent` or `vcpkg`/`conan` for dependency management
+- Separate build directories for debug and release
+
+## Security
+
+- Bounds-checked alternatives: `std::span`, `std::string_view`, `at()` over `[]`
+- Stack buffer overflow: use `std::array` or `std::vector` instead of C arrays
+- Format string safety: never pass user input as a format string
+- Integer overflow: use safe integer libraries or explicit checks
+- Run ASan, UBSan, and thread sanitizer in CI
+
+## Anti-Patterns
+
+- Manual `new`/`delete` without RAII wrappers
+- `void*` and C-style casts in C++ code
+- Macros for constants or functions (use `constexpr` and templates)
+- Header-only libraries for large codebases (compile time explosion)
+- Premature optimization with `inline` or manual memory management

package/skills/development/go.md

@@ -0,0 +1,129 @@
+<!--
+skills/development/go.md — Go Best Practices — Use this skill when writing, reviewing, or debugging Go code.
+
+Use this skill when writing, reviewing, or debugging Go code. ## Project Structure
+-->
+# Go Best Practices
+
+Use this skill when writing, reviewing, or debugging Go code.
+
+## Project Structure
+
+```
+cmd/
+  server/
+    main.go
+internal/
+  handler/
+  service/
+  repository/
+  model/
+pkg/
+  shared-lib/
+go.mod
+go.sum
+```
+
+- `cmd/` for entry points; `internal/` for private packages; `pkg/` for public libraries
+- Keep `main.go` thin: parse config, wire dependencies, start server
+- One package per directory; package name matches directory name
+
+## Tooling
+
+| Tool | Purpose |
+|---|---|
+| gofmt / goimports | Formatting (non-negotiable) |
+| golangci-lint | Comprehensive linting (replaces individual linters) |
+| go vet | Static analysis |
+| go test -race | Race condition detection |
+| govulncheck | Vulnerability scanning |
+| delve | Debugging |
+
+## Error Handling
+
+- Return errors as the last return value
+- Wrap errors with context: `fmt.Errorf("fetch user %d: %w", id, err)`
+- Use `errors.Is` and `errors.As` for type-safe error checking
+- Define sentinel errors for expected conditions: `var ErrNotFound = errors.New("not found")`
+- Custom error types for structured error information
+- Handle every returned error; never use `_` for errors without justification
+
+## Concurrency
+
+### Goroutines
+- Always ensure goroutines can terminate (use context cancellation)
+- Use `sync.WaitGroup` to wait for goroutine completion
+- Prefer `errgroup.Group` for goroutines that return errors
+- Limit goroutine count with semaphores or worker pools
+
+### Channels
+- Prefer channels for communication; mutexes for protecting shared state
+- Buffered channels for known producer-consumer rates
+- Close channels from the sender side only
+- Use `select` with `context.Done()` for cancellation
+
+### Context
+- Pass `context.Context` as the first parameter to functions
+- Use `context.WithTimeout` for all external calls
+- Propagate context through the entire call chain
+- Never store context in structs
+
+## Interfaces
+
+- Define interfaces at the consumer, not the provider
+- Keep interfaces small: 1-3 methods
+- Accept interfaces, return structs
+- Use interface embedding for composition
+- Avoid premature abstraction; extract interfaces when a second implementation appears
+
+## Testing
+
+- Table-driven tests for multiple cases
+- `testing.T.Helper()` for test helper functions
+- Use `testify` or standard library assertions
+- `httptest` for HTTP handler testing
+- Test with `-race` flag in CI
+- Use `t.Parallel()` for independent tests
+- `go test -coverprofile` for coverage analysis
+
+## Performance
+
+- Profile with `pprof`: CPU, memory, goroutine, mutex
+- Avoid allocations in hot paths; reuse buffers with `sync.Pool`
+- Pre-allocate slices with `make([]T, 0, expectedCap)`
+- Use `strings.Builder` for string concatenation
+- Benchmark with `testing.B` before and after optimization
+- Avoid reflection in performance-critical code
+
+## Patterns
+
+### Dependency Injection
+- Constructor functions: `func NewService(repo Repository) *Service`
+- Wire dependencies in `main.go` or with a DI tool (wire, fx)
+- Interfaces for external dependencies enable testing with mocks
+
+### Options Pattern
+- `func NewServer(opts ...Option)` for configurable constructors
+- Each option is a function that modifies a config struct
+- Provides good defaults with optional overrides
+
+### Middleware
+- `func(http.Handler) http.Handler` for HTTP middleware
+- Chain: logging, auth, rate limiting, recovery
+- Keep middleware focused on cross-cutting concerns
+
+## Security
+
+- Use `crypto/rand` for random values, never `math/rand` for security
+- Validate all user input at handler boundaries
+- Use parameterized queries; avoid string interpolation in SQL
+- Set timeouts on HTTP servers and clients
+- Use `gosec` and `govulncheck` in CI
+
+## Anti-Patterns
+
+- `init()` functions for complex initialization (hard to test)
+- Package-level mutable variables (hidden global state)
+- Ignoring errors with `_`
+- Goroutine leaks (no cancellation mechanism)
+- Overusing `interface{}` / `any` when concrete types are known