@cubis/foundry 0.3.71 → 0.3.73

package/workflows/powers/cli-developer/SKILL.md

@@ -1,116 +1,173 @@
 ---
-name: "cli-developer"
-displayName: "CLI Developer"
-description: "Build intuitive, cross-platform CLI tools with argument parsing, interactive prompts, progress indicators, and shell completions across Node.js, Python, and Go"
-keywords:
-  [
-    "cli",
-    "command-line",
-    "terminal",
-    "argument parsing",
-    "shell completion",
-    "interactive prompt",
-    "progress bar",
-    "commander",
-    "click",
-    "typer",
-    "cobra",
-  ]
+name: cli-developer
+description: Build command-line interfaces with argument parsing, subcommands, interactive prompts, terminal UX, output formatting, and cross-platform compatibility.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
 ---
 
 # CLI Developer
 
-## Overview
+## Purpose
 
-Senior CLI developer expertise for building fast, intuitive command-line tools across Node.js, Python, and Go ecosystems. Focus on <50ms startup time, comprehensive shell completions, and delightful developer UX.
+Guide the design and implementation of command-line interfaces. Covers argument parsing, subcommand architecture, interactive prompts, terminal UX patterns, and cross-platform compatibility.
 
 ## When to Use
 
-- Building CLI tools and terminal applications
-- Implementing argument parsing and subcommands
-- Creating interactive prompts and forms
-- Adding progress bars and spinners
-- Implementing shell completions (bash, zsh, fish)
-- Optimizing CLI performance and startup time
-- Designing command hierarchies and flag conventions
+- Building a new CLI tool from scratch
+- Adding subcommands or flags to an existing CLI
+- Implementing interactive prompts and wizards
+- Designing CLI output formats (tables, JSON, progress bars)
+- Making CLIs cross-platform (Windows, macOS, Linux)
+- Reviewing CLI usability and documentation
 
-## Core Workflow
+## Instructions
 
-1. Analyze UX — identify user workflows, command hierarchy, common tasks
-2. Design commands — plan subcommands, flags, arguments, configuration
-3. Implement — build with appropriate CLI framework for the language
-4. Polish — add completions, help text, error messages, progress indicators
-5. Test — cross-platform testing, performance benchmarks
+### Step 1 — Design the Command Structure
 
-## Quick Reference
+**Naming conventions**:
 
-### Framework Selection
+- Use verb-noun pattern for commands: `create project`, `list users`, `delete cache`
+- Short flags for common options: `-v` (verbose), `-q` (quiet), `-f` (force)
+- Long flags for clarity: `--output`, `--format`, `--dry-run`
+- Positional arguments for required inputs: `mycli deploy <environment>`
 
-| Language | Recommended   | Alternative     |
-| -------- | ------------- | --------------- |
-| Node.js  | Commander.js  | Yargs, oclif    |
-| Python   | Typer         | Click, argparse |
-| Go       | Cobra + Viper | urfave/cli      |
-
-### Command Structure
+**Subcommand architecture**:
 
 ```
-mycli                           # Root command
-├── init [options]              # Simple command
+mycli
+├── init              (one-time setup)
 ├── config
-│   ├── get <key>              # Nested subcommand
+│   ├── get <key>
 │   ├── set <key> <value>
 │   └── list
-├── deploy [environment]        # Command with args
-│   ├── --dry-run              # Flag
-│   ├── --force
-│   └── --config <file>        # Option with value
-└── plugins
-    ├── install <name>
-    ├── list
-    └── remove <name>
+├── project
+│   ├── create <name>
+│   ├── list
+│   └── delete <id>
+└── deploy <env>      (positional argument)
 ```
 
-### Exit Codes
-
-| Code | Meaning           |
-| ---- | ----------------- |
-| 0    | Success           |
-| 1    | General error     |
-| 2    | Invalid arguments |
-| 77   | Permission denied |
-| 127  | Not found         |
-| 130  | Ctrl+C (SIGINT)   |
-
-## Constraints
-
-### MUST DO
-
-- Keep startup time under 50ms
-- Provide clear, actionable error messages
-- Support `--help` and `--version` flags
-- Use consistent flag naming conventions
-- Handle SIGINT (Ctrl+C) gracefully
-- Validate user input early
-- Support both interactive and non-interactive modes
-- Test on Windows, macOS, and Linux
-
-### MUST NOT DO
-
-- Block on synchronous I/O unnecessarily
-- Print to stdout if output will be piped
-- Use colors when output is not a TTY
-- Break existing command signatures (breaking changes)
-- Require interactive input in CI/CD environments
-- Hardcode paths or platform-specific logic
-- Ship without shell completions
-
-## Steering Files
-
-| File                 | Load When                                                    |
-| -------------------- | ------------------------------------------------------------ |
-| `design-patterns.md` | Command hierarchy, flags, config layers, plugin architecture |
-| `node-cli.md`        | Commander, Yargs, Inquirer, Chalk, Ora                       |
-| `python-cli.md`      | Typer, Click, argparse, Rich, questionary                    |
-| `go-cli.md`          | Cobra, Viper, Bubble Tea, progress bars                      |
-| `ux-patterns.md`     | Progress indicators, colors, help text, error messages       |
+**Rules**:
+
+- Every command has `--help` (automatic with good parsers)
+- Support `--version` at the root level
+- Common flags go on the root command, specific flags on subcommands
+- Use `--dry-run` for destructive operations
+
+### Step 2 — Implement Argument Parsing
+
+**Choose the right parser**:
+| Language | Recommended |
+|----------|-------------|
+| Node.js | Commander, yargs, citty |
+| Python | Click, Typer |
+| Go | Cobra, urfave/cli |
+| Rust | Clap |
+
+**Validation**:
+
+- Validate early, fail with clear error messages
+- Show the closest valid option on typos (did-you-mean)
+- Report all validation errors at once, not one at a time
+
+### Step 3 — Design Terminal UX
+
+**Output hierarchy**:
+
+1. Primary output goes to stdout (pipeable)
+2. Status messages go to stderr (logs, progress)
+3. Errors go to stderr with non-zero exit code
+
+**Formatting**:
+
+- Default: human-readable (tables, colors, emoji)
+- `--json`: machine-parseable JSON output
+- `--quiet`: errors only, minimal output
+- Detect TTY: disable colors and interactivity when piped
+
+**Progress feedback**:
+
+- Spinner for short operations (< 10s)
+- Progress bar for operations with known total
+- Log lines for multi-step operations (✓ Step 1... ✓ Step 2...)
+
+**Colors** (use sparingly):
+
+- Green: success
+- Red: error
+- Yellow: warning
+- Blue/cyan: information
+- Dim/gray: secondary information
+- Always support `NO_COLOR` environment variable
+
+### Step 4 — Interactive Prompts
+
+**When to prompt**:
+
+- Missing required information not provided as flags
+- Confirmation before destructive operations
+- Multi-step wizards for complex setup
+
+**Prompt types**:
+| Type | When |
+|------|------|
+| Text input | Free-form strings (names, paths) |
+| Password | Secrets (mask input) |
+| Select | Single choice from a list |
+| Multi-select | Multiple choices from a list |
+| Confirm | Yes/no decision |
+
+**Rules**:
+
+- Show defaults in brackets: `Port [3000]:`
+- Allow non-interactive mode via flags (CI environments)
+- Validate input inline and let the user retry
+- Support Ctrl+C graceful cancellation
+
+### Step 5 — Error Handling & Exit Codes
+
+**Exit codes**:
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Misuse / invalid arguments |
+| 126 | Permission denied |
+| 127 | Command not found |
+| 130 | Terminated by Ctrl+C (SIGINT) |
+
+**Error messages**:
+
+```
+Error: Could not connect to database at localhost:5432
+  Cause: Connection refused
+  Fix: Ensure PostgreSQL is running: `pg_ctl start`
+```
+
+Include: what failed, why, and how to fix.
+
+## Output Format
+
+```
+## CLI Architecture
+[command structure and flag design]
+
+## Implementation
+[code with argument parsing and command handlers]
+
+## UX Considerations
+[output formatting, interactivity, error handling]
+```
+
+## Examples
+
+**User**: "Build a CLI for managing our API deployments"
+
+**Response approach**: Design subcommand structure (deploy, rollback, status, logs). Implement with Commander/Click/Cobra. Add deploy confirmation prompt, progress bar for upload, JSON output for CI. Handle rollback with `--to-version` flag.
+
+**User**: "Our CLI has bad error messages — users don't know what went wrong"
+
+**Response approach**: Audit error handling. Add context to every error (what, why, fix). Implement did-you-mean for typos. Add `--verbose` flag for debug output. Ensure proper exit codes for scripting.

package/workflows/powers/cpp-pro/POWER.md

@@ -0,0 +1,111 @@
+````markdown
+---
+inclusion: manual
+name: cpp-pro
+description: "Use for modern C++23-era systems and application engineering with RAII, value semantics, toolchain awareness, and performance-safe design."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "2.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Cpp Pro
+
+## Purpose
+
+Use for modern C++23-era systems and application engineering with RAII, value semantics, toolchain awareness, and performance-safe design.
+
+## When to Use
+
+- Building or refactoring modern C++ libraries, services, or native apps.
+- Improving ownership, templates, performance boundaries, or build structure.
+- Fixing correctness or maintainability issues in large native codebases.
+
+## Instructions
+
+1. Confirm toolchain, standard level, and module/library boundaries.
+2. Prefer RAII, value semantics, and explicit ownership over raw lifetime juggling.
+3. Keep templates readable and avoid metaprogramming when simpler designs suffice.
+4. Separate correctness fixes from performance tuning unless the two are inseparable.
+5. Validate with targeted tests, warnings, and native build checks.
+
+### Baseline standards
+
+- Compile with `-std=c++23` (or project minimum). Enable `-Wall -Wextra -Wpedantic -Werror`.
+- Use smart pointers (`unique_ptr`, `shared_ptr`) instead of raw `new`/`delete`. Raw pointers are non-owning observers only.
+- Prefer value types and move semantics over heap allocation and pointer indirection.
+- Mark functions `[[nodiscard]]` when ignoring the return value is always a bug.
+- Use `constexpr` and `consteval` for compile-time computation where possible.
+- Keep header includes minimal. Use forward declarations to reduce coupling.
+
+### RAII and ownership
+
+- Every resource (memory, file handle, mutex lock, socket) must be managed by an RAII wrapper.
+- Use `unique_ptr` for exclusive ownership, `shared_ptr` only when shared ownership is genuinely required.
+- Prefer moving over copying for expensive types. Delete copy constructors when copying is semantically wrong.
+- Use `std::optional` instead of nullable pointers for optional values.
+- Scope-guard patterns for cleanup when RAII wrappers don't exist yet.
+
+### Templates and generics
+
+- Use concepts (C++20/23) to constrain template parameters. Unconstrained templates produce unreadable error messages.
+- Prefer `auto` with trailing return types for function templates. Avoid deep template nesting.
+- Keep template definitions in headers. Use explicit instantiation only for build-time improvement in large projects.
+- Prefer `std::variant` and `std::visit` over inheritance hierarchies for closed type sets.
+
+### Concurrency
+
+- Use `std::jthread` and `std::stop_token` for manageable thread lifecycles.
+- Prefer `std::mutex` with `std::lock_guard`/`std::scoped_lock` — never lock/unlock manually.
+- Use `std::atomic` for lock-free counters and flags. Profile before choosing lock-free data structures.
+- Propagate cancellation through `stop_token` rather than shared booleans.
+- Run ThreadSanitizer in CI for all concurrent code paths.
+
+### Performance
+
+- Profile with `perf`, `VTune`, or `Instruments` before optimizing. Measure hot paths, not hunches.
+- Prefer contiguous containers (`std::vector`) over node-based containers (`std::list`, `std::map`) for cache efficiency.
+- Use `std::string_view` and `std::span` to avoid unnecessary copies at function boundaries.
+- Avoid virtual dispatch in hot loops. Prefer CRTP or `std::variant` when static dispatch suffices.
+- Enable LTO for release builds. Benchmark with and without to verify gains.
+
+### Debugging
+
+- Compile debug builds with `-g -O0 -fsanitize=address,undefined`.
+- Use `static_assert` for compile-time invariants. Use `assert` for runtime invariants in debug mode.
+- When debugging crashes: reproduce under sanitizers first, then inspect with gdb/lldb.
+- Use structured error types (`std::expected` in C++23) instead of exceptions for recoverable errors in performance-sensitive code.
+
+### Constraints
+
+- Avoid raw `new`/`delete` — use smart pointers or containers.
+- Avoid c-style casts — use `static_cast`, `dynamic_cast`, `const_cast`, or `reinterpret_cast` with justification.
+- Avoid deep inheritance hierarchies — prefer composition and type erasure.
+- Avoid `using namespace std;` in headers — pollutes all includers.
+- Avoid exceptions for control flow — use them for truly exceptional conditions only.
+- Avoid premature micro-optimization without profiling evidence.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+| File                                           | Load when                                                                                                           |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `references/raii-and-modern-cpp-checklist.md`  | RAII patterns, smart pointer selection, value semantics, move correctness, or template constraint review is needed. |
+| `references/move-semantics-and-value-types.md` | Move constructor/assignment design, perfect forwarding, copy elision, or value category questions arise.            |
+| `references/template-and-concepts-patterns.md` | Concept constraints, SFINAE replacement, variadic templates, or compile-time computation patterns are needed.       |
+| `references/concurrency-primitives.md`         | Thread management, mutex strategies, atomic operations, lock-free patterns, or coroutine design is needed.          |
+| `references/performance-and-profiling.md`      | Cache optimization, allocation reduction, benchmark setup, or profiler-driven tuning is needed.                     |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with cpp pro best practices in this project"
+- "Review my cpp pro implementation for issues"
+````

package/workflows/powers/cpp-pro/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: cpp-pro
+description: "Use for modern C++23-era systems and application engineering with RAII, value semantics, toolchain awareness, and performance-safe design."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "2.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Cpp Pro
+
+## Purpose
+
+Use for modern C++23-era systems and application engineering with RAII, value semantics, toolchain awareness, and performance-safe design.
+
+## When to Use
+
+- Building or refactoring modern C++ libraries, services, or native apps.
+- Improving ownership, templates, performance boundaries, or build structure.
+- Fixing correctness or maintainability issues in large native codebases.
+
+## Instructions
+
+1. Confirm toolchain, standard level, and module/library boundaries.
+2. Prefer RAII, value semantics, and explicit ownership over raw lifetime juggling.
+3. Keep templates readable and avoid metaprogramming when simpler designs suffice.
+4. Separate correctness fixes from performance tuning unless the two are inseparable.
+5. Validate with targeted tests, warnings, and native build checks.
+
+### Baseline standards
+
+- Compile with `-std=c++23` (or project minimum). Enable `-Wall -Wextra -Wpedantic -Werror`.
+- Use smart pointers (`unique_ptr`, `shared_ptr`) instead of raw `new`/`delete`. Raw pointers are non-owning observers only.
+- Prefer value types and move semantics over heap allocation and pointer indirection.
+- Mark functions `[[nodiscard]]` when ignoring the return value is always a bug.
+- Use `constexpr` and `consteval` for compile-time computation where possible.
+- Keep header includes minimal. Use forward declarations to reduce coupling.
+
+### RAII and ownership
+
+- Every resource (memory, file handle, mutex lock, socket) must be managed by an RAII wrapper.
+- Use `unique_ptr` for exclusive ownership, `shared_ptr` only when shared ownership is genuinely required.
+- Prefer moving over copying for expensive types. Delete copy constructors when copying is semantically wrong.
+- Use `std::optional` instead of nullable pointers for optional values.
+- Scope-guard patterns for cleanup when RAII wrappers don't exist yet.
+
+### Templates and generics
+
+- Use concepts (C++20/23) to constrain template parameters. Unconstrained templates produce unreadable error messages.
+- Prefer `auto` with trailing return types for function templates. Avoid deep template nesting.
+- Keep template definitions in headers. Use explicit instantiation only for build-time improvement in large projects.
+- Prefer `std::variant` and `std::visit` over inheritance hierarchies for closed type sets.
+
+### Concurrency
+
+- Use `std::jthread` and `std::stop_token` for manageable thread lifecycles.
+- Prefer `std::mutex` with `std::lock_guard`/`std::scoped_lock` — never lock/unlock manually.
+- Use `std::atomic` for lock-free counters and flags. Profile before choosing lock-free data structures.
+- Propagate cancellation through `stop_token` rather than shared booleans.
+- Run ThreadSanitizer in CI for all concurrent code paths.
+
+### Performance
+
+- Profile with `perf`, `VTune`, or `Instruments` before optimizing. Measure hot paths, not hunches.
+- Prefer contiguous containers (`std::vector`) over node-based containers (`std::list`, `std::map`) for cache efficiency.
+- Use `std::string_view` and `std::span` to avoid unnecessary copies at function boundaries.
+- Avoid virtual dispatch in hot loops. Prefer CRTP or `std::variant` when static dispatch suffices.
+- Enable LTO for release builds. Benchmark with and without to verify gains.
+
+### Debugging
+
+- Compile debug builds with `-g -O0 -fsanitize=address,undefined`.
+- Use `static_assert` for compile-time invariants. Use `assert` for runtime invariants in debug mode.
+- When debugging crashes: reproduce under sanitizers first, then inspect with gdb/lldb.
+- Use structured error types (`std::expected` in C++23) instead of exceptions for recoverable errors in performance-sensitive code.
+
+### Constraints
+
+- Avoid raw `new`/`delete` — use smart pointers or containers.
+- Avoid c-style casts — use `static_cast`, `dynamic_cast`, `const_cast`, or `reinterpret_cast` with justification.
+- Avoid deep inheritance hierarchies — prefer composition and type erasure.
+- Avoid `using namespace std;` in headers — pollutes all includers.
+- Avoid exceptions for control flow — use them for truly exceptional conditions only.
+- Avoid premature micro-optimization without profiling evidence.
+
+## Output Format
+
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
+
+## References
+
+| File                                           | Load when                                                                                                           |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `references/raii-and-modern-cpp-checklist.md`  | RAII patterns, smart pointer selection, value semantics, move correctness, or template constraint review is needed. |
+| `references/move-semantics-and-value-types.md` | Move constructor/assignment design, perfect forwarding, copy elision, or value category questions arise.            |
+| `references/template-and-concepts-patterns.md` | Concept constraints, SFINAE replacement, variadic templates, or compile-time computation patterns are needed.       |
+| `references/concurrency-primitives.md`         | Thread management, mutex strategies, atomic operations, lock-free patterns, or coroutine design is needed.          |
+| `references/performance-and-profiling.md`      | Cache optimization, allocation reduction, benchmark setup, or profiler-driven tuning is needed.                     |
+
+## Scripts
+
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
+
+## Examples
+
+- "Help me with cpp pro best practices in this project"
+- "Review my cpp pro implementation for issues"