dot-ai-evals 0.1.0__tar.gz

dot_ai_evals-0.1.0/.agents/skills/cli-ux-designer/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: cli-ux-designer
+description: This skill should be used when the user asks to "design a CLI", "improve command structure", "format terminal output", "review CLI usability", "design help text", or "add flags and arguments". Automatically activates when designing new CLI tools, improving command interfaces, formatting terminal output, or reviewing CLI usability. Not for GUI/web design, backend APIs, or shell scripting.
+---
+
+# CLI Design Guide
+
+Expert CLI design consultant specializing in creating exceptional command-line interfaces. Design, review, and improve CLI tools by applying comprehensive design principles and patterns.
+
+## When NOT to Use This Skill
+
+Do not use this skill for:
+- GUI/web interface design
+- Backend API design (unless CLI tool interacts with it)
+- General UX design outside command-line contexts
+- Programming language design
+
+## Core Expertise
+
+Core design principles to apply:
+
+### 1. Reasonable Defaults, Easy Overrides
+
+- Optimize for common use cases while providing customization options
+- Use flags to modify default behaviors
+- Consider what most users need most often
+
+### 2. Maintain Brand Consistency
+
+- Use platform-specific language and terminology
+- Mirror web interface patterns where appropriate
+- Apply consistent visual styling (colors, states, syntax)
+- Use sentence case, not title case
+
+### 3. Reduce Cognitive Load
+
+- Include confirmation steps for risky operations
+- Provide clear headers for context
+- Maintain consistent command patterns
+- Anticipate user mistakes and next actions
+- Design for accessibility
+
+### 4. Terminal-First with Web Integration
+
+- Keep users in terminal when possible
+- Provide easy paths to web interface when needed
+- Include `--web` flags for browser actions
+- Output relevant URLs after operations
+
+## Command Structure Expertise
+
+Ensure commands follow this consistent pattern:
+
+| tool | `<command>` | `<subcommand>` | [value]  | [flags] | [value] |
+| ---- | ----------- | -------------- | -------- | ------- | ------- |
+| cli  | issue       | view           | 234      | --web   | -       |
+| cli  | pr          | create         | -        | --title | "Title" |
+| cli  | repo        | fork           | org/repo | --clone | false   |
+
+**Components:**
+
+- **Command**: The object to interact with
+- **Subcommand**: The action to take on that object
+- **Flag**: Modifiers with long version (`--state`) and often shorthand (`-s`)
+- **Values**: IDs, owner/repo pairs, URLs, branch names, file names
+
+**Language Guidelines:**
+
+- Use unambiguous language that can't be confused
+- Use shorter phrases when possible and appropriate
+- Use flags for modifiers of actions, avoid making modifiers their own commands
+- Use understood shorthands to save characters
+
+## Decision Frameworks
+
+Use these when making CLI design choices:
+
+**Flag vs. Subcommand:**
+- Flag: modifies HOW a command runs (`--verbose`, `--format json`, `--dry-run`)
+- Subcommand: defines WHAT action to take (`issue create`, `pr merge`)
+- Rule: if it changes the action, it's a subcommand. If it changes the behavior, it's a flag.
+
+**Interactive vs. Non-interactive:**
+- Default to interactive when: user is exploring, multiple choices needed, destructive action requires confirmation
+- Default to non-interactive when: command is commonly scripted, output is piped, CI/CD context
+- Always: provide `--yes`/`-y` to skip confirmations, `--no-input` to disable all prompts
+
+**Output Format:**
+- Human-readable (default): colors, tables, summaries when stdout is a TTY
+- Machine-readable (piped): no colors, tab-delimited or JSON when stdout is not a TTY
+- Explicit: `--format json|table|csv` flag to override detection
+
+**Error Handling:**
+- Exit code 0: success
+- Exit code 1: general error
+- Exit code 2: usage error (wrong flags/args)
+- Always: error message to stderr, suggested fix when possible
+
+## Visual Design System Knowledge
+
+### Typography
+
+- Assume monospace fonts
+- Use **bold** for emphasis and repository names
+- Create hierarchy with spacing and weight
+- No italics (unreliable support)
+
+### Color Usage
+
+Apply the 8 basic ANSI colors:
+
+- **Green**: Success, open states
+- **Red**: Failure, closed states
+- **Yellow**: Warnings, draft states
+- **Blue**: Information, links
+- **Cyan**: Branch names, special identifiers
+- **Magenta**: Special highlights
+- **Gray**: Secondary information, labels
+- **White/Default**: Primary text
+
+**Guidelines:**
+
+- Only enhance meaning, never communicate meaning solely through color
+- Consider users can customize terminal colors
+- Some terminals don't support 256-color sequences reliably
+
+For complete ANSI color codes and escape sequences, see `./references/ansi-color-reference.md`.
+
+### Iconography
+
+Use Unicode symbols consistently:
+
+- `✓` Success
+- `✗` Failure
+- `!` Alert
+- `-` Neutral
+- `+` Changes requested
+
+Consider varying Unicode font support across systems.
+
+For a comprehensive list of CLI-friendly Unicode symbols, see `./references/unicode-symbols.md`.
+
+## Component Pattern Expertise
+
+### Lists
+
+- Use tabular format with headers
+- Show state through color
+- Include relevant contextual information
+
+For a complete list view example, see `./references/examples/list-view-example.txt`.
+
+### Detail Views
+
+- Show comprehensive information
+- Indent body content
+- Include URLs at bottom
+
+### Prompts
+
+- **Yes/No**: Default in caps, for confirmations
+- **Short text**: Single-line input with autocomplete
+- **Long text**: Multi-line with editor option
+- **Radio select**: Choose one option
+- **Multi-select**: Choose multiple options
+- Always provide flag alternatives to prompts
+
+For an interactive prompt example, see `./references/examples/interactive-prompt-example.txt`.
+
+### Help Pages
+
+Required sections: Usage, Core commands, Flags, Learn more, Inherited flags
+Optional sections: Additional commands, Examples, Arguments, Feedback
+
+For a complete help text example, see `./references/examples/help-text-example.txt`.
+
+### Syntax Conventions
+
+- `<required-args>` in angle brackets
+- `[optional-args]` in square brackets
+- `{mutually-exclusive}` in braces
+- `repeatable...` with ellipsis
+- Use dash-case for multi-word variables
+
+## Anti-patterns
+
+Avoid these common CLI design mistakes:
+
+| Anti-pattern | Better Approach |
+|-------------|-----------------|
+| Deeply nested subcommands (`tool group sub action`) | Max 2 levels: `tool command [flags]` |
+| Inconsistent flag naming (`--no-color` vs `--disable-colors`) | Pick one convention and apply everywhere |
+| Interactive prompts with no flag alternatives | Every prompt must have a `--flag` equivalent |
+| Cryptic error messages ("Error: 1") | Include what went wrong, why, and how to fix |
+| Silent failures (exit 0 on error) | Non-zero exit codes for failures, stderr for errors |
+| Missing `--help` on subcommands | Every command level should have help |
+| Mixing stdout data with status messages | Data to stdout, progress/status to stderr |
+
+## Technical Considerations
+
+### Script Automation Support
+
+- Provide flags for all interactive elements
+- Output machine-readable formats when piped
+- Use tabs as delimiters for structured data
+- Remove colors/formatting in non-terminal output
+- Include exact timestamps and full data
+
+### Accessibility
+
+- Use punctuation for screen reader pauses
+- Don't rely solely on color for meaning
+- Support high contrast and custom themes
+- Design for cognitive accessibility
+
+## Success Criteria
+
+Recommendations are successful when:
+- Commands follow consistent patterns across the tool
+- Help text is clear with useful examples
+- Visual hierarchy guides users naturally
+- Both interactive and scriptable use cases work
+- Accessibility requirements are met

dot_ai_evals-0.1.0/.agents/skills/cli-ux-designer/references/ansi-color-reference.md

@@ -0,0 +1,222 @@
+# ANSI Color Reference for CLI Design
+
+This reference provides comprehensive ANSI color codes for terminal styling in CLI applications.
+
+## Basic 16 Colors (3/4-bit)
+
+### Standard Colors
+
+| Color   | Foreground | Background | Use Cases                              |
+|---------|-----------|-----------|----------------------------------------|
+| Black   | `\033[30m` | `\033[40m` | Default text, dividers                |
+| Red     | `\033[31m` | `\033[41m` | Errors, failures, closed states       |
+| Green   | `\033[32m` | `\033[42m` | Success, open states, confirmations   |
+| Yellow  | `\033[33m` | `\033[43m` | Warnings, draft states, caution       |
+| Blue    | `\033[34m` | `\033[44m` | Information, links, metadata          |
+| Magenta | `\033[35m` | `\033[45m` | Special highlights, tags              |
+| Cyan    | `\033[36m` | `\033[46m` | Branch names, identifiers, emphasis   |
+| White   | `\033[37m` | `\033[47m` | Primary text, headings                |
+
+### Bright/Bold Variants
+
+| Color        | Foreground | Background | Use Cases                       |
+|--------------|-----------|-----------|----------------------------------|
+| Bright Black (Gray) | `\033[90m` | `\033[100m` | Secondary text, labels, timestamps |
+| Bright Red          | `\033[91m` | `\033[101m` | Critical errors, destructive actions |
+| Bright Green        | `\033[92m` | `\033[102m` | Strong success indicators       |
+| Bright Yellow       | `\033[93m` | `\033[103m` | Important warnings              |
+| Bright Blue         | `\033[94m` | `\033[104m` | Highlighted information         |
+| Bright Magenta      | `\033[95m` | `\033[105m` | Special status indicators       |
+| Bright Cyan         | `\033[96m` | `\033[106m` | Emphasized identifiers          |
+| Bright White        | `\033[97m` | `\033[107m` | Maximum emphasis, alerts        |
+
+## Text Styling
+
+| Style           | Code       | Reset      | Use Cases                    |
+|----------------|-----------|-----------|------------------------------|
+| Bold           | `\033[1m`  | `\033[22m` | Headers, emphasis            |
+| Dim            | `\033[2m`  | `\033[22m` | Secondary info, deprecation  |
+| Italic         | `\033[3m`  | `\033[23m` | Not recommended (poor support) |
+| Underline      | `\033[4m`  | `\033[24m` | Links, emphasis              |
+| Blink          | `\033[5m`  | `\033[25m` | Avoid (accessibility issue)  |
+| Reverse        | `\033[7m`  | `\033[27m` | Selection, current item      |
+| Strikethrough  | `\033[9m`  | `\033[29m` | Deprecated, removed items    |
+
+## Reset Codes
+
+| Reset Type     | Code       | Description                        |
+|---------------|-----------|-------------------------------------|
+| All attributes | `\033[0m`  | Clear all styling and colors       |
+| Foreground     | `\033[39m` | Reset to default text color        |
+| Background     | `\033[49m` | Reset to default background        |
+
+## 256 Color Palette (8-bit)
+
+### Syntax
+- **Foreground**: `\033[38;5;<n>m` where `<n>` is 0-255
+- **Background**: `\033[48;5;<n>m` where `<n>` is 0-255
+
+### Color Ranges
+
+**0-15**: Standard and bright colors (same as 16-color palette above)
+
+**16-231**: 6×6×6 RGB color cube
+- Formula: `16 + 36×r + 6×g + b` where r,g,b are 0-5
+- Example: `\033[38;5;196m` = bright red (r=5, g=0, b=0)
+
+**232-255**: Grayscale ramp (24 shades from dark to light)
+- Example: `\033[38;5;240m` = dark gray
+- Example: `\033[38;5;250m` = light gray
+
+### Common 256 Colors
+
+| Color Description | Code (FG)       | Hex Approximation |
+|------------------|----------------|-------------------|
+| Dark Red         | `\033[38;5;88m` | `#870000`        |
+| Orange           | `\033[38;5;208m`| `#ff8700`        |
+| Dark Green       | `\033[38;5;28m` | `#008700`        |
+| Teal             | `\033[38;5;30m` | `#008787`        |
+| Navy Blue        | `\033[38;5;18m` | `#000087`        |
+| Purple           | `\033[38;5;93m` | `#8700ff`        |
+| Dark Gray        | `\033[38;5;240m`| `#585858`        |
+| Light Gray       | `\033[38;5;250m`| `#bcbcbc`        |
+
+## RGB True Color (24-bit)
+
+### Syntax
+- **Foreground**: `\033[38;2;<r>;<g>;<b>m` where r,g,b are 0-255
+- **Background**: `\033[48;2;<r>;<g>;<b>m` where r,g,b are 0-255
+
+### Examples
+
+```bash
+# Brand-specific red (RGB: 255, 59, 48)
+\033[38;2;255;59;48m
+
+# Brand-specific blue (RGB: 0, 122, 255)
+\033[38;2;0;122;255m
+
+# Custom gray (RGB: 142, 142, 147)
+\033[38;2;142;142;147m
+```
+
+## Combining Codes
+
+Multiple styles can be combined using semicolons:
+
+```bash
+# Bold red text
+\033[1;31m
+
+# Underlined bright green
+\033[4;92m
+
+# Bold, underlined cyan on dark gray background
+\033[1;4;36;100m
+
+# 256-color bold blue
+\033[1;38;5;27m
+
+# RGB true color bold
+\033[1;38;2;255;59;48m
+```
+
+## Compatibility Notes
+
+### Terminal Support
+
+| Feature        | Support Level | Notes                               |
+|---------------|--------------|--------------------------------------|
+| 16 colors     | Universal    | Safe to use everywhere              |
+| Bold/Dim      | Universal    | Widely supported                    |
+| Underline     | Universal    | Widely supported                    |
+| Italic        | Limited      | Unreliable, avoid in production     |
+| Blink         | Limited      | Accessibility issue, avoid          |
+| 256 colors    | Good         | Most modern terminals, test first   |
+| RGB colors    | Moderate     | Many modern terminals, fallback needed |
+
+### Detection Strategy
+
+```bash
+# Check COLORTERM environment variable
+if [ "$COLORTERM" = "truecolor" ] || [ "$COLORTERM" = "24bit" ]; then
+    # RGB true color supported
+elif [ "$TERM" = "xterm-256color" ]; then
+    # 256 colors supported
+else
+    # Use basic 16 colors only
+fi
+```
+
+## Best Practices
+
+### 1. Stick to Basic Colors for Maximum Compatibility
+Use the 16 basic colors for critical information. Reserve 256/RGB for branding or progressive enhancement.
+
+### 2. Always Reset After Styling
+```bash
+echo "\033[32mSuccess!\033[0m"  # Good
+echo "\033[32mSuccess!"          # Bad - affects subsequent output
+```
+
+### 3. Provide Monochrome Fallback
+Ensure meaning isn't conveyed through color alone. Use symbols and text:
+```bash
+echo "✓ \033[32mSuccess\033[0m"  # Good - symbol + color
+echo "\033[32mSuccess\033[0m"    # Risky - color only
+```
+
+### 4. Respect User Preferences
+- Check `NO_COLOR` environment variable
+- Detect if output is piped/redirected
+- Support `--no-color` flag
+
+### 5. Test in Multiple Terminals
+- macOS Terminal
+- iTerm2
+- Windows Terminal
+- VS Code integrated terminal
+- Linux terminals (GNOME Terminal, Konsole, etc.)
+
+## Quick Reference: Semantic Color Usage
+
+| Meaning       | Recommended Color | Code        |
+|--------------|------------------|------------|
+| Success      | Green            | `\033[32m` |
+| Error        | Red              | `\033[31m` |
+| Warning      | Yellow           | `\033[33m` |
+| Info         | Blue             | `\033[34m` |
+| Highlight    | Cyan             | `\033[36m` |
+| Subtle       | Bright Black (Gray) | `\033[90m` |
+| Emphasis     | Bold             | `\033[1m`  |
+| Link         | Blue Underline   | `\033[4;34m` |
+
+## Language-Specific Libraries
+
+### JavaScript/Node.js
+- `chalk` - Terminal string styling
+- `kleur` - Lightweight alternative to chalk
+- `picocolors` - Minimal ANSI color library
+
+### Python
+- `colorama` - Cross-platform colored terminal text
+- `termcolor` - ANSI color formatting
+- `rich` - Advanced terminal formatting
+
+### Go
+- `fatih/color` - Color package for Go
+- `charmbracelet/lipgloss` - Style definitions for TUI
+
+### Rust
+- `colored` - Coloring terminal
+- `ansi_term` - ANSI terminal colors and styles
+
+### Ruby
+- `colorize` - String coloring
+- `tty-color` - Terminal color capabilities detection
+
+## Additional Resources
+
+- ANSI Escape Codes Standard: ECMA-48
+- Terminal emulator test suite: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
+- Color testing tool: https://github.com/termstandard/colors

dot_ai_evals-0.1.0/.agents/skills/cli-ux-designer/references/examples/help-text-example.txt

@@ -0,0 +1,41 @@
+gh issue - Manage issues
+
+USAGE
+  gh issue <command> [flags]
+
+CORE COMMANDS
+  create:      Create a new issue
+  list:        List issues in a repository
+  view:        Display the details of an issue
+  close:       Close an issue
+  reopen:      Reopen a closed issue
+  comment:     Add a comment to an issue
+  edit:        Edit an issue
+  status:      Show status of relevant issues
+
+ADDITIONAL COMMANDS
+  delete:      Delete an issue
+  lock:        Lock issue conversation
+  pin:         Pin an issue
+  transfer:    Transfer issue to another repository
+  unlock:      Unlock issue conversation
+  unpin:       Unpin an issue
+
+FLAGS
+  -R, --repo [HOST/]OWNER/REPO   Select another repository using the [HOST/]OWNER/REPO format
+
+INHERITED FLAGS
+      --help                      Show help for command
+
+EXAMPLES
+  $ gh issue create --title "Bug report" --body "Something is broken"
+  $ gh issue list --assignee @me --state open
+  $ gh issue view 123 --web
+  $ gh issue close 456 --comment "Fixed in PR #789"
+
+LEARN MORE
+  Use 'gh <command> <subcommand> --help' for more information about a command.
+  Read the manual at https://cli.github.com/manual
+
+FEEDBACK
+  Open an issue using 'gh issue create -R cli/cli'

dot_ai_evals-0.1.0/.agents/skills/cli-ux-designer/references/examples/interactive-prompt-example.txt

@@ -0,0 +1,45 @@
+Creating a new issue in cli/cli
+
+? Title: Fix color rendering in Windows Terminal
+
+? Body: <Received>
+  What's the issue?
+
+  When running `gh issue list` in Windows Terminal, the ANSI color codes
+  are not rendering correctly. Text appears with escape sequences visible
+  instead of colored output.
+
+  Steps to reproduce:
+  1. Open Windows Terminal
+  2. Run `gh issue list`
+  3. Observe raw ANSI codes in output
+
+  Expected: Colored, formatted output
+  Actual: Raw escape sequences visible
+
+? What labels should be added? (Press <space> to select, <enter> to submit)
+  ◯ bug
+  ◉ enhancement
+  ◯ documentation
+  ◯ help wanted
+  ◉ windows
+  ◯ good first issue
+
+? What's the next action?
+  → Create issue
+    Create issue and open in browser
+    Save as draft
+    Cancel
+
+✓ Created issue #4524: Fix color rendering in Windows Terminal
+  https://github.com/cli/cli/issues/4524
+
+───────────────────────────────────────────────────────────────────
+
+Note: This example demonstrates:
+- Clear question prompts with context
+- Multi-line text input (indicated by <Received>)
+- Multi-select checkboxes (◯ unchecked, ◉ checked)
+- Radio selection menu (→ indicates current selection)
+- Success confirmation with symbol and link
+- Visual separator for command completion

dot_ai_evals-0.1.0/.agents/skills/cli-ux-designer/references/examples/list-view-example.txt

@@ -0,0 +1,25 @@
+Showing 15 of 127 issues in cli/cli
+
+#4523  Fix help text formatting for nested commands            (enhancement)       20h
+#4521  Add support for GitHub Enterprise Server 3.8            (feature)           1d
+#4518  Bug: color output in piped commands                     (bug)               2d
+#4510  Documentation improvements for auth commands            (documentation)     4d
+#4507  Performance: speed up repository clone operations       (enhancement)       5d
+#4498  Add interactive mode for issue creation                 (feature)           1w
+#4492  Fix crash when using --web flag without browser         (bug)               1w
+#4485  Improve error messages for network failures             (enhancement)       2w
+#4478  Support custom templates for pull requests              (feature)           2w
+#4471  Update dependencies to latest versions                  (maintenance)       2w
+#4465  Add bash completion for subcommands                     (enhancement)       3w
+#4459  Fix regression in release list command                  (bug)               3w
+#4451  Support for organization-level configurations           (feature)           1mo
+#4447  Improve accessibility of table output                   (accessibility)     1mo
+#4440  Add support for draft pull requests in list view        (enhancement)       1mo
+
+Legend:
+  • Green = open
+  • Red = closed
+  • Yellow = draft
+  • Gray = secondary information
+
+Note: Times shown are relative to current date