aigroup-workflow 2.2.0 → 2.2.2

package/skills/infra/cli-developer/SKILL.md

@@ -1,113 +1,113 @@
----
-name: cli-developer
-description: Use when building CLI tools, implementing argument parsing, or adding interactive prompts. Invoke for parsing flags and subcommands, displaying progress bars and spinners, generating bash/zsh/fish completion scripts, CLI design, shell completions, and cross-platform terminal applications using commander, click, typer, or cobra.
-license: MIT
-metadata:
-  author: https://github.com/Jeffallan
-  version: "1.1.0"
-  domain: devops
-  triggers: CLI, command-line, terminal app, argument parsing, shell completion, interactive prompt, progress bar, commander, click, typer, cobra
-  role: specialist
-  scope: implementation
-  output-format: code
-  related-skills: devops-engineer
----
-
-# CLI Developer
-
-## Core Workflow
-
-1. **Analyze UX** — Identify user workflows, command hierarchy, common tasks. Validate by listing all commands and their expected `--help` output before writing code.
-2. **Design commands** — Plan subcommands, flags, arguments, configuration. Confirm flag naming is consistent and no existing signatures are broken.
-3. **Implement** — Build with the appropriate CLI framework for the language (see Reference Guide below). After wiring up commands, run `<cli> --help` to verify help text renders correctly and `<cli> --version` to confirm version output.
-4. **Polish** — Add completions, help text, error messages, progress indicators. Verify TTY detection for color output and graceful SIGINT handling.
-5. **Test** — Run cross-platform smoke tests; benchmark startup time (target: <50ms).
-
-## Reference Guide
-
-Load detailed guidance based on context:
-
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Design Patterns | `references/design-patterns.md` | Subcommands, flags, config, architecture |
-| Node.js CLIs | `references/node-cli.md` | commander, yargs, inquirer, chalk |
-| Python CLIs | `references/python-cli.md` | click, typer, argparse, rich |
-| Go CLIs | `references/go-cli.md` | cobra, viper, bubbletea |
-| UX Patterns | `references/ux-patterns.md` | Progress bars, colors, help text |
-
-## Quick-Start Example
-
-### Node.js (commander)
-
-```js
-#!/usr/bin/env node
-// npm install commander
-const { program } = require('commander');
-
-program
-  .name('mytool')
-  .description('Example CLI')
-  .version('1.0.0');
-
-program
-  .command('greet <name>')
-  .description('Greet a user')
-  .option('-l, --loud', 'uppercase the greeting')
-  .action((name, opts) => {
-    const msg = `Hello, ${name}!`;
-    console.log(opts.loud ? msg.toUpperCase() : msg);
-  });
-
-program.parse();
-```
-
-For Python (click/typer) and Go (cobra) quick-start examples, see `references/python-cli.md` and `references/go-cli.md`.
-
-## 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** — use async reads or stream processing instead.
-- **Print to stdout when output will be piped** — write logs/diagnostics to stderr.
-- **Use colors when output is not a TTY** — detect before applying color:
-  ```js
-  // Node.js
-  const useColor = process.stdout.isTTY;
-  ```
-  ```python
-  # Python
-  import sys
-  use_color = sys.stdout.isatty()
-  ```
-  ```go
-  // Go
-  import "golang.org/x/term"
-  useColor := term.IsTerminal(int(os.Stdout.Fd()))
-  ```
-- **Break existing command signatures** — treat flag/subcommand renames as breaking changes.
-- **Require interactive input in CI/CD environments** — always provide non-interactive fallbacks via flags or env vars.
-- **Hardcode paths or platform-specific logic** — use `os.homedir()` / `os.UserHomeDir()` / `Path.home()` instead.
-- **Ship without shell completions** — all three frameworks above have built-in completion generation.
-
-## Output Templates
-
-When implementing CLI features, provide:
-1. Command structure (main entry point, subcommands)
-2. Configuration handling (files, env vars, flags)
-3. Core implementation with error handling
-4. Shell completion scripts if applicable
-5. Brief explanation of UX decisions
-
-## Knowledge Reference
-
-CLI frameworks (commander, yargs, oclif, click, typer, argparse, cobra, viper), terminal UI (chalk, inquirer, rich, bubbletea), testing (snapshot testing, E2E), distribution (npm, pip, homebrew, releases), performance optimization
+---
+name: cli-developer
+description: Use when building CLI tools, implementing argument parsing, or adding interactive prompts. Invoke for parsing flags and subcommands, displaying progress bars and spinners, generating bash/zsh/fish completion scripts, CLI design, shell completions, and cross-platform terminal applications using commander, click, typer, or cobra.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: devops
+  triggers: CLI, command-line, terminal app, argument parsing, shell completion, interactive prompt, progress bar, commander, click, typer, cobra
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: devops-engineer
+---
+
+# CLI Developer
+
+## Core Workflow
+
+1. **Analyze UX** — Identify user workflows, command hierarchy, common tasks. Validate by listing all commands and their expected `--help` output before writing code.
+2. **Design commands** — Plan subcommands, flags, arguments, configuration. Confirm flag naming is consistent and no existing signatures are broken.
+3. **Implement** — Build with the appropriate CLI framework for the language (see Reference Guide below). After wiring up commands, run `<cli> --help` to verify help text renders correctly and `<cli> --version` to confirm version output.
+4. **Polish** — Add completions, help text, error messages, progress indicators. Verify TTY detection for color output and graceful SIGINT handling.
+5. **Test** — Run cross-platform smoke tests; benchmark startup time (target: <50ms).
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Design Patterns | `references/design-patterns.md` | Subcommands, flags, config, architecture |
+| Node.js CLIs | `references/node-cli.md` | commander, yargs, inquirer, chalk |
+| Python CLIs | `references/python-cli.md` | click, typer, argparse, rich |
+| Go CLIs | `references/go-cli.md` | cobra, viper, bubbletea |
+| UX Patterns | `references/ux-patterns.md` | Progress bars, colors, help text |
+
+## Quick-Start Example
+
+### Node.js (commander)
+
+```js
+#!/usr/bin/env node
+// npm install commander
+const { program } = require('commander');
+
+program
+  .name('mytool')
+  .description('Example CLI')
+  .version('1.0.0');
+
+program
+  .command('greet <name>')
+  .description('Greet a user')
+  .option('-l, --loud', 'uppercase the greeting')
+  .action((name, opts) => {
+    const msg = `Hello, ${name}!`;
+    console.log(opts.loud ? msg.toUpperCase() : msg);
+  });
+
+program.parse();
+```
+
+For Python (click/typer) and Go (cobra) quick-start examples, see `references/python-cli.md` and `references/go-cli.md`.
+
+## 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** — use async reads or stream processing instead.
+- **Print to stdout when output will be piped** — write logs/diagnostics to stderr.
+- **Use colors when output is not a TTY** — detect before applying color:
+  ```js
+  // Node.js
+  const useColor = process.stdout.isTTY;
+  ```
+  ```python
+  # Python
+  import sys
+  use_color = sys.stdout.isatty()
+  ```
+  ```go
+  // Go
+  import "golang.org/x/term"
+  useColor := term.IsTerminal(int(os.Stdout.Fd()))
+  ```
+- **Break existing command signatures** — treat flag/subcommand renames as breaking changes.
+- **Require interactive input in CI/CD environments** — always provide non-interactive fallbacks via flags or env vars.
+- **Hardcode paths or platform-specific logic** — use `os.homedir()` / `os.UserHomeDir()` / `Path.home()` instead.
+- **Ship without shell completions** — all three frameworks above have built-in completion generation.
+
+## Output Templates
+
+When implementing CLI features, provide:
+1. Command structure (main entry point, subcommands)
+2. Configuration handling (files, env vars, flags)
+3. Core implementation with error handling
+4. Shell completion scripts if applicable
+5. Brief explanation of UX decisions
+
+## Knowledge Reference
+
+CLI frameworks (commander, yargs, oclif, click, typer, argparse, cobra, viper), terminal UI (chalk, inquirer, rich, bubbletea), testing (snapshot testing, E2E), distribution (npm, pip, homebrew, releases), performance optimization

package/skills/infra/cli-developer/references/design-patterns.md

@@ -1,221 +1,221 @@
-# CLI Design Patterns
-
-## Command Hierarchy
-
-```
-mycli                           # Root command
-├── init [options]              # Simple command
-├── config
-│   ├── get <key>              # Nested subcommand
-│   ├── set <key> <value>
-│   └── list
-├── deploy [environment]        # Command with args
-│   ├── --dry-run              # Flag
-│   ├── --force
-│   └── --config <file>        # Option with value
-└── plugins
-    ├── install <name>
-    ├── list
-    └── remove <name>
-```
-
-## Flag Conventions
-
-```bash
-# Boolean flags (presence = true)
-mycli deploy --force --dry-run
-
-# Short + long forms
-mycli -v --verbose
-mycli -c config.yml --config config.yml
-
-# Required vs optional
-mycli deploy <env>              # Positional (required)
-mycli deploy --env production   # Flag (optional)
-
-# Multiple values
-mycli install pkg1 pkg2 pkg3    # Variadic args
-mycli --exclude node_modules --exclude .git
-```
-
-## Configuration Layers
-
-Priority order (highest to lowest):
-
-1. **Command-line flags** - Explicit user intent
-2. **Environment variables** - Runtime context
-3. **Config files (project)** - `.myclirc`, `mycli.config.js`
-4. **Config files (user)** - `~/.myclirc`, `~/.config/mycli/config.yml`
-5. **Config files (system)** - `/etc/mycli/config.yml`
-6. **Defaults** - Hard-coded sensible defaults
-
-```javascript
-// Example config resolution
-const config = {
-  ...systemDefaults,
-  ...loadSystemConfig(),
-  ...loadUserConfig(),
-  ...loadProjectConfig(),
-  ...loadEnvVars(),
-  ...parseCliFlags(),
-};
-```
-
-## Exit Codes
-
-Standard POSIX exit codes:
-
-```javascript
-const EXIT_CODES = {
-  SUCCESS: 0,
-  GENERAL_ERROR: 1,
-  MISUSE: 2,              // Invalid arguments
-  PERMISSION_DENIED: 77,
-  NOT_FOUND: 127,
-  SIGINT: 130,            // Ctrl+C
-};
-```
-
-## Plugin Architecture
-
-```
-mycli/
-├── core/                      # Core functionality
-├── plugins/
-│   ├── aws/                  # Plugin: AWS integration
-│   │   ├── package.json
-│   │   └── index.js
-│   └── github/               # Plugin: GitHub integration
-│       ├── package.json
-│       └── index.js
-└── plugin-loader.js          # Discovery & loading
-```
-
-Plugin discovery:
-1. Check `~/.mycli/plugins/`
-2. Check `node_modules/mycli-plugin-*`
-3. Check `MYCLI_PLUGIN_PATH` env var
-
-## Error Handling Patterns
-
-```javascript
-// Good: Actionable error messages
-Error: Config file not found at /path/to/config.yml
-
-Tried locations:
-  • ./mycli.config.yml
-  • ~/.myclirc
-  • /etc/mycli/config.yml
-
-Run 'mycli init' to create a config file, or use --config to specify location.
-
-// Bad: Unhelpful errors
-Error: ENOENT
-```
-
-## Interactive vs Non-Interactive
-
-```javascript
-// Detect if running in CI/CD
-const isCI = process.env.CI === 'true' || !process.stdout.isTTY;
-
-if (isCI) {
-  // Non-interactive: fail fast with clear errors
-  if (!options.environment) {
-    throw new Error('--environment required in non-interactive mode');
-  }
-} else {
-  // Interactive: prompt user
-  const environment = await prompt({
-    type: 'select',
-    message: 'Select environment:',
-    choices: ['development', 'staging', 'production'],
-  });
-}
-```
-
-## State Management
-
-```
-~/.mycli/
-├── config.yml           # User configuration
-├── cache/               # Cached data
-│   ├── plugins.json
-│   └── api-responses/
-├── credentials.json     # Sensitive data (600 perms)
-└── state.json          # Session state
-```
-
-## Performance Patterns
-
-```javascript
-// Lazy loading: Don't load unused dependencies
-if (command === 'deploy') {
-  const deploy = require('./commands/deploy'); // Load on demand
-  await deploy.run();
-}
-
-// Caching: Avoid repeated API calls
-const cache = new Cache('~/.mycli/cache', { ttl: 3600 });
-let plugins = await cache.get('plugins');
-if (!plugins) {
-  plugins = await fetchPlugins();
-  await cache.set('plugins', plugins);
-}
-
-// Async operations: Don't block unnecessarily
-await Promise.all([
-  validateConfig(),
-  checkForUpdates(),
-  loadPlugins(),
-]);
-```
-
-## Versioning & Updates
-
-```javascript
-// Check for updates (non-blocking)
-checkForUpdates().then(update => {
-  if (update.available) {
-    console.log(`Update available: ${update.version}`);
-    console.log(`Run: npm install -g mycli@latest`);
-  }
-}).catch(() => {
-  // Silently fail - don't interrupt user workflow
-});
-
-// Version compatibility
-const MIN_NODE_VERSION = '18.0.0';
-if (!semver.satisfies(process.version, `>=${MIN_NODE_VERSION}`)) {
-  console.error(`mycli requires Node.js ${MIN_NODE_VERSION} or higher`);
-  process.exit(1);
-}
-```
-
-## Help Text Design
-
-```
-USAGE
-  mycli deploy [environment] [options]
-
-ARGUMENTS
-  environment  Target environment (development|staging|production)
-
-OPTIONS
-  -c, --config <file>  Path to config file
-  -f, --force          Skip confirmation prompts
-  -d, --dry-run        Preview changes without executing
-  -v, --verbose        Show detailed output
-
-EXAMPLES
-  # Deploy to production
-  mycli deploy production
-
-  # Preview staging deployment
-  mycli deploy staging --dry-run
-
-  # Use custom config
-  mycli deploy --config ./custom.yml
-
-Learn more: https://docs.mycli.dev/deploy
-```
+# CLI Design Patterns
+
+## Command Hierarchy
+
+```
+mycli                           # Root command
+├── init [options]              # Simple command
+├── config
+│   ├── get <key>              # Nested subcommand
+│   ├── set <key> <value>
+│   └── list
+├── deploy [environment]        # Command with args
+│   ├── --dry-run              # Flag
+│   ├── --force
+│   └── --config <file>        # Option with value
+└── plugins
+    ├── install <name>
+    ├── list
+    └── remove <name>
+```
+
+## Flag Conventions
+
+```bash
+# Boolean flags (presence = true)
+mycli deploy --force --dry-run
+
+# Short + long forms
+mycli -v --verbose
+mycli -c config.yml --config config.yml
+
+# Required vs optional
+mycli deploy <env>              # Positional (required)
+mycli deploy --env production   # Flag (optional)
+
+# Multiple values
+mycli install pkg1 pkg2 pkg3    # Variadic args
+mycli --exclude node_modules --exclude .git
+```
+
+## Configuration Layers
+
+Priority order (highest to lowest):
+
+1. **Command-line flags** - Explicit user intent
+2. **Environment variables** - Runtime context
+3. **Config files (project)** - `.myclirc`, `mycli.config.js`
+4. **Config files (user)** - `~/.myclirc`, `~/.config/mycli/config.yml`
+5. **Config files (system)** - `/etc/mycli/config.yml`
+6. **Defaults** - Hard-coded sensible defaults
+
+```javascript
+// Example config resolution
+const config = {
+  ...systemDefaults,
+  ...loadSystemConfig(),
+  ...loadUserConfig(),
+  ...loadProjectConfig(),
+  ...loadEnvVars(),
+  ...parseCliFlags(),
+};
+```
+
+## Exit Codes
+
+Standard POSIX exit codes:
+
+```javascript
+const EXIT_CODES = {
+  SUCCESS: 0,
+  GENERAL_ERROR: 1,
+  MISUSE: 2,              // Invalid arguments
+  PERMISSION_DENIED: 77,
+  NOT_FOUND: 127,
+  SIGINT: 130,            // Ctrl+C
+};
+```
+
+## Plugin Architecture
+
+```
+mycli/
+├── core/                      # Core functionality
+├── plugins/
+│   ├── aws/                  # Plugin: AWS integration
+│   │   ├── package.json
+│   │   └── index.js
+│   └── github/               # Plugin: GitHub integration
+│       ├── package.json
+│       └── index.js
+└── plugin-loader.js          # Discovery & loading
+```
+
+Plugin discovery:
+1. Check `~/.mycli/plugins/`
+2. Check `node_modules/mycli-plugin-*`
+3. Check `MYCLI_PLUGIN_PATH` env var
+
+## Error Handling Patterns
+
+```javascript
+// Good: Actionable error messages
+Error: Config file not found at /path/to/config.yml
+
+Tried locations:
+  • ./mycli.config.yml
+  • ~/.myclirc
+  • /etc/mycli/config.yml
+
+Run 'mycli init' to create a config file, or use --config to specify location.
+
+// Bad: Unhelpful errors
+Error: ENOENT
+```
+
+## Interactive vs Non-Interactive
+
+```javascript
+// Detect if running in CI/CD
+const isCI = process.env.CI === 'true' || !process.stdout.isTTY;
+
+if (isCI) {
+  // Non-interactive: fail fast with clear errors
+  if (!options.environment) {
+    throw new Error('--environment required in non-interactive mode');
+  }
+} else {
+  // Interactive: prompt user
+  const environment = await prompt({
+    type: 'select',
+    message: 'Select environment:',
+    choices: ['development', 'staging', 'production'],
+  });
+}
+```
+
+## State Management
+
+```
+~/.mycli/
+├── config.yml           # User configuration
+├── cache/               # Cached data
+│   ├── plugins.json
+│   └── api-responses/
+├── credentials.json     # Sensitive data (600 perms)
+└── state.json          # Session state
+```
+
+## Performance Patterns
+
+```javascript
+// Lazy loading: Don't load unused dependencies
+if (command === 'deploy') {
+  const deploy = require('./commands/deploy'); // Load on demand
+  await deploy.run();
+}
+
+// Caching: Avoid repeated API calls
+const cache = new Cache('~/.mycli/cache', { ttl: 3600 });
+let plugins = await cache.get('plugins');
+if (!plugins) {
+  plugins = await fetchPlugins();
+  await cache.set('plugins', plugins);
+}
+
+// Async operations: Don't block unnecessarily
+await Promise.all([
+  validateConfig(),
+  checkForUpdates(),
+  loadPlugins(),
+]);
+```
+
+## Versioning & Updates
+
+```javascript
+// Check for updates (non-blocking)
+checkForUpdates().then(update => {
+  if (update.available) {
+    console.log(`Update available: ${update.version}`);
+    console.log(`Run: npm install -g mycli@latest`);
+  }
+}).catch(() => {
+  // Silently fail - don't interrupt user workflow
+});
+
+// Version compatibility
+const MIN_NODE_VERSION = '18.0.0';
+if (!semver.satisfies(process.version, `>=${MIN_NODE_VERSION}`)) {
+  console.error(`mycli requires Node.js ${MIN_NODE_VERSION} or higher`);
+  process.exit(1);
+}
+```
+
+## Help Text Design
+
+```
+USAGE
+  mycli deploy [environment] [options]
+
+ARGUMENTS
+  environment  Target environment (development|staging|production)
+
+OPTIONS
+  -c, --config <file>  Path to config file
+  -f, --force          Skip confirmation prompts
+  -d, --dry-run        Preview changes without executing
+  -v, --verbose        Show detailed output
+
+EXAMPLES
+  # Deploy to production
+  mycli deploy production
+
+  # Preview staging deployment
+  mycli deploy staging --dry-run
+
+  # Use custom config
+  mycli deploy --config ./custom.yml
+
+Learn more: https://docs.mycli.dev/deploy
+```