Skip to content

Commit 51bf6f3

Browse files
yuWormyuWorm
committed
change to claude agent
1 parent af26f48 commit 51bf6f3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+3795
-0
lines changed

‎.claude/skills/jcottam-spark-terminal-ui/AGENTS.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Developer Experience TUI
2+
3+
**Version 0.1.0**
4+
DevEx
5+
January 2026
6+
7+
> **Note:**
8+
> This document is mainly for agents and LLMs to follow when maintaining,
9+
> generating, or refactoring codebases. Humans may also find it useful,
10+
> but guidance here is optimized for automation and consistency by AI-assisted workflows.
11+
12+
---
13+
14+
## Abstract
15+
16+
Comprehensive developer experience guide for building TypeScript terminal user interfaces using Ink (React for CLIs) and Clack prompts. Contains 42 rules across 8 categories, prioritized by impact from critical (rendering optimization, input handling) to incremental (robustness and compatibility). Each rule includes detailed explanations, real-world TypeScript examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
17+
18+
---
19+
20+
## Table of Contents
21+
22+
1. [Rendering & Output](references/_sections.md#1-rendering-&-output) — **CRITICAL**
23+
- 1.1 [Batch Terminal Output in Single Write](references/render-single-write.md) — CRITICAL (eliminates partial frame flicker)
24+
- 1.2 [Defer ANSI Escape Code Generation to Final Output](references/render-escape-sequence-batching.md) — HIGH (reduces intermediate string allocations)
25+
- 1.3 [Overwrite Content Instead of Clear and Redraw](references/render-overwrite-dont-clear.md) — CRITICAL (eliminates blank frame flicker)
26+
- 1.4 [Target 60fps for Smooth Animation](references/render-60fps-baseline.md) — CRITICAL (16ms frame budget for perceived smoothness)
27+
- 1.5 [Update Only Changed Regions](references/render-partial-updates.md) — CRITICAL (reduces bandwidth by 80-95%)
28+
- 1.6 [Use Synchronized Output Protocol for Animations](references/render-synchronized-output.md) — CRITICAL (eliminates 100% of mid-frame flicker)
29+
2. [Input & Keyboard](references/_sections.md#2-input-&-keyboard) — **CRITICAL**
30+
- 2.1 [Always Provide Escape Routes](references/input-escape-routes.md) — CRITICAL (prevents user frustration and stuck states)
31+
- 2.2 [Handle Modifier Keys Correctly](references/input-modifier-keys.md) — CRITICAL (prevents missed shortcuts and input bugs)
32+
- 2.3 [Provide Immediate Visual Feedback for Input](references/input-immediate-feedback.md) — CRITICAL (<100ms response feels instant)
33+
- 2.4 [Use isActive Option for Focus Management](references/input-isactive-focus.md) — HIGH (prevents input conflicts between components)
34+
- 2.5 [Use useInput Hook for Keyboard Handling](references/input-useinput-hook.md) — CRITICAL (prevents raw stdin complexity)
35+
3. [Component Patterns](references/_sections.md#3-component-patterns) — **HIGH**
36+
- 3.1 [Use Border Styles for Visual Structure](references/tuicomp-border-styles.md) — MEDIUM (reduces visual parsing time by 30-50%)
37+
- 3.2 [Use Box Component with Flexbox for Layouts](references/tuicomp-box-flexbox.md) — HIGH (eliminates manual position calculations)
38+
- 3.3 [Use measureElement for Dynamic Sizing](references/tuicomp-measure-element.md) — HIGH (enables responsive layouts based on content)
39+
- 3.4 [Use Percentage Widths for Responsive Layouts](references/tuicomp-percentage-widths.md) — HIGH (prevents overflow on 100% of terminal sizes)
40+
- 3.5 [Use Static Component for Log Output](references/tuicomp-static-for-logs.md) — HIGH (prevents log lines from re-rendering)
41+
- 3.6 [Use Text Component for All Visible Content](references/tuicomp-text-styling.md) — HIGH (prevents 100% of styling bugs from raw strings)
42+
4. [State & Lifecycle](references/_sections.md#4-state-&-lifecycle) — **HIGH**
43+
- 4.1 [Always Clean Up Effects on Unmount](references/tuistate-cleanup-effects.md) — HIGH (prevents memory leaks and orphaned timers)
44+
- 4.2 [Memoize Expensive Computations with useMemo](references/tuistate-usememo-expensive.md) — MEDIUM (avoids recalculating on every render)
45+
- 4.3 [Stabilize Callbacks with useCallback](references/tuistate-usecallback-stable.md) — MEDIUM (prevents unnecessary re-renders in children)
46+
- 4.4 [Use Functional State Updates to Avoid Stale Closures](references/tuistate-functional-updates.md) — HIGH (prevents stale state bugs in callbacks)
47+
- 4.5 [Use useApp Hook for Application Lifecycle](references/tuistate-useapp-exit.md) — HIGH (prevents terminal state corruption on exit)
48+
5. [Prompt Design](references/_sections.md#5-prompt-design) — **MEDIUM-HIGH**
49+
- 5.1 [Build Custom Prompts with @clack/core](references/prompt-custom-render.md) — MEDIUM (enables specialized input patterns)
50+
- 5.2 [Handle Cancellation Gracefully with isCancel](references/prompt-cancellation.md) — MEDIUM-HIGH (prevents crashes and ensures clean exit)
51+
- 5.3 [Use Clack group() for Multi-Step Prompts](references/prompt-group-flow.md) — MEDIUM-HIGH (enables sequential prompts with shared state)
52+
- 5.4 [Use Spinner and Tasks for Long Operations](references/prompt-spinner-tasks.md) — MEDIUM-HIGH (prevents perceived hang during async work)
53+
- 5.5 [Validate Input Early with Descriptive Messages](references/prompt-validation.md) — MEDIUM-HIGH (prevents invalid data from propagating)
54+
6. [UX & Feedback](references/_sections.md#6-ux-&-feedback) — **MEDIUM**
55+
- 6.1 [Show Next Steps After Completion](references/ux-next-steps.md) — MEDIUM (reduces support requests by providing clear guidance)
56+
- 6.2 [Show Progress for Operations Over 1 Second](references/ux-progress-indicators.md) — MEDIUM (prevents perceived hangs and user frustration)
57+
- 6.3 [Use Colors Semantically and Consistently](references/ux-color-semantics.md) — MEDIUM (reduces time-to-comprehension by 2-3×)
58+
- 6.4 [Use Intro and Outro for Session Framing](references/ux-intro-outro.md) — MEDIUM (improves perceived quality by 30-40% in user studies)
59+
- 6.5 [Write Actionable Error Messages](references/ux-error-messages.md) — MEDIUM (reduces user frustration and support requests)
60+
7. [Configuration & CLI](references/_sections.md#7-configuration-&-cli) — **MEDIUM**
61+
- 7.1 [Implement Comprehensive Help System](references/tuicfg-help-system.md) — MEDIUM (enables self-service and reduces support burden)
62+
- 7.2 [Prefer Flags Over Positional Arguments](references/tuicfg-flags-over-args.md) — MEDIUM (reduces user errors by 50% through self-documentation)
63+
- 7.3 [Provide Sensible Defaults for All Options](references/tuicfg-sensible-defaults.md) — MEDIUM (reduces friction for common use cases)
64+
- 7.4 [Support Machine-Readable Output Format](references/tuicfg-json-output.md) — MEDIUM (enables scripting and tool integration)
65+
- 7.5 [Support Standard Environment Variables](references/tuicfg-env-vars.md) — MEDIUM (enables scripting and CI integration)
66+
8. [Robustness & Compatibility](references/_sections.md#8-robustness-&-compatibility) — **LOW-MEDIUM**
67+
- 8.1 [Always Restore Terminal State on Exit](references/robust-terminal-restore.md) — LOW-MEDIUM (prevents broken terminal after crashes)
68+
- 8.2 [Degrade Gracefully for Limited Terminals](references/robust-graceful-degradation.md) — LOW-MEDIUM (maintains usability in 100% of terminal environments)
69+
- 8.3 [Detect TTY and Adjust Behavior Accordingly](references/robust-tty-detection.md) — LOW-MEDIUM (prevents 100% of CI hangs from interactive prompts)
70+
- 8.4 [Handle Process Signals Gracefully](references/robust-signal-handling.md) — LOW-MEDIUM (enables clean shutdown and resource cleanup)
71+
- 8.5 [Use Meaningful Exit Codes](references/robust-exit-codes.md) — LOW-MEDIUM (enables proper error handling in scripts)
72+
73+
---
74+
75+
## References
76+
77+
1. [https://github.com/bombshell-dev/clack](https://github.com/bombshell-dev/clack)
78+
2. [https://github.com/vadimdemedes/ink](https://github.com/vadimdemedes/ink)
79+
3. [https://github.com/vadimdemedes/ink-ui](https://github.com/vadimdemedes/ink-ui)
80+
4. [https://clig.dev/](https://clig.dev/)
81+
5. [https://textual.textualize.io/blog/2024/12/12/algorithms-for-high-performance-terminal-apps/](https://textual.textualize.io/blog/2024/12/12/algorithms-for-high-performance-terminal-apps/)
82+
83+
---
84+
85+
## Source Files
86+
87+
This document was compiled from individual reference files. For detailed editing or extension:
88+
89+
| File | Description |
90+
|------|-------------|
91+
| [references/_sections.md](references/_sections.md) | Category definitions and impact ordering |
92+
| [assets/templates/_template.md](assets/templates/_template.md) | Template for creating new rules |
93+
| [SKILL.md](SKILL.md) | Quick reference entry point |
94+
| [metadata.json](metadata.json) | Version and reference URLs |

‎.claude/skills/jcottam-spark-terminal-ui/README.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Developer Experience TUI Best Practices
2+
3+
Comprehensive developer experience guide for building TypeScript terminal user interfaces using Ink (React for CLIs), @clack/prompts, and @clack/core.
4+
5+
## Overview
6+
7+
This skill provides 42 performance and UX optimization rules for TUI development, organized by impact from critical to incremental.
8+
9+
### Structure
10+
11+
```
12+
developer-experience-tui/
13+
├── SKILL.md # Entry point with quick reference
14+
├── AGENTS.md # Compiled comprehensive guide
15+
├── metadata.json # Version, org, references
16+
├── README.md # This file
17+
└── rules/
18+
├── _sections.md # Category definitions
19+
├── render-*.md # Rendering optimization rules (6)
20+
├── input-*.md # Input handling rules (5)
21+
├── comp-*.md # Component pattern rules (6)
22+
├── state-*.md # State management rules (5)
23+
├── prompt-*.md # Prompt design rules (5)
24+
├── ux-*.md # UX feedback rules (5)
25+
├── config-*.md # Configuration rules (5)
26+
└── robust-*.md # Robustness rules (5)
27+
```
28+
29+
## Getting Started
30+
31+
### Installation
32+
33+
```bash
34+
pnpm install
35+
```
36+
37+
### Building
38+
39+
```bash
40+
pnpm build
41+
```
42+
43+
### Validation
44+
45+
```bash
46+
pnpm validate
47+
```
48+
49+
## Creating a New Rule
50+
51+
1. Determine the appropriate category based on the rule's focus
52+
2. Create a new file with the category prefix: `{prefix}-{description}.md`
53+
3. Include YAML frontmatter with required fields
54+
4. Follow the template structure with incorrect/correct examples
55+
56+
### Category Prefixes
57+
58+
| Prefix | Category | Impact |
59+
|--------|----------|--------|
60+
| `render-` | Rendering & Output | CRITICAL |
61+
| `input-` | Input & Keyboard | CRITICAL |
62+
| `comp-` | Component Patterns | HIGH |
63+
| `state-` | State & Lifecycle | HIGH |
64+
| `prompt-` | Prompt Design | MEDIUM-HIGH |
65+
| `ux-` | UX & Feedback | MEDIUM |
66+
| `config-` | Configuration & CLI | MEDIUM |
67+
| `robust-` | Robustness & Compatibility | LOW-MEDIUM |
68+
69+
## Rule File Structure
70+
71+
```markdown
72+
---
73+
title: Rule Title Here
74+
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
75+
impactDescription: Brief quantified impact (e.g., "eliminates flicker")
76+
tags: prefix, keyword1, keyword2
77+
---
78+
79+
## Rule Title Here
80+
81+
Brief explanation of WHY this matters (1-3 sentences).
82+
83+
**Incorrect (problem description):**
84+
85+
\`\`\`typescript
86+
// Bad example with comments explaining the cost
87+
\`\`\`
88+
89+
**Correct (solution description):**
90+
91+
\`\`\`typescript
92+
// Good example with minimal diff from incorrect
93+
\`\`\`
94+
95+
Reference: [Source](https://example.com)
96+
```
97+
98+
## File Naming Convention
99+
100+
Rules follow the pattern: `{prefix}-{description}.md`
101+
102+
- `prefix`: Category identifier (3-7 lowercase chars)
103+
- `description`: Kebab-case description of the rule
104+
105+
Examples:
106+
- `render-single-write.md`
107+
- `input-useinput-hook.md`
108+
- `prompt-group-flow.md`
109+
110+
## Impact Levels
111+
112+
| Level | Description |
113+
|-------|-------------|
114+
| CRITICAL | Must fix - causes major performance or UX issues |
115+
| HIGH | Should fix - significant improvement opportunity |
116+
| MEDIUM-HIGH | Recommended - noticeable improvement |
117+
| MEDIUM | Good practice - incremental improvement |
118+
| LOW-MEDIUM | Nice to have - polish and edge cases |
119+
| LOW | Optional - advanced optimization |
120+
121+
## Scripts
122+
123+
- `pnpm validate` - Validate skill structure and content
124+
- `pnpm build` - Build AGENTS.md from rules
125+
126+
## Contributing
127+
128+
1. Read existing rules to understand the style and depth expected
129+
2. Each rule should have a clear incorrect/correct example pair
130+
3. Quantify impact where possible (N× improvement, Nms reduction)
131+
4. Include references to authoritative sources
132+
5. Run validation before submitting
133+
134+
## Key Libraries Covered
135+
136+
- **[Ink](https://github.com/vadimdemedes/ink)** - React for interactive command-line apps
137+
- **[@inkjs/ui](https://github.com/vadimdemedes/ink-ui)** - UI components for Ink
138+
- **[@clack/prompts](https://github.com/bombshell-dev/clack)** - Beautiful prompt components
139+
- **[@clack/core](https://github.com/bombshell-dev/clack)** - Unstyled prompt primitives
140+
141+
## Acknowledgments
142+
143+
- [Command Line Interface Guidelines](https://clig.dev/) - Comprehensive CLI design principles
144+
- [Textualize Blog](https://textual.textualize.io/blog/) - High-performance TUI algorithms
145+
- [Kitty Keyboard Protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) - Modern keyboard handling

‎.claude/skills/jcottam-spark-terminal-ui/SKILL.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
name: terminal-ui
3+
description: Terminal User Interface (TUI) performance and UX guidelines for TypeScript applications using Ink and Clack. This skill should be used when building CLI tools, interactive terminal prompts, or developer tooling with TUI components. Triggers on tasks involving TUI components, CLI prompts, terminal rendering, keyboard input handling, or developer tooling.
4+
---
5+
6+
# DevEx Developer Experience TUI Best Practices
7+
8+
Comprehensive developer experience guide for building TypeScript terminal user interfaces using Ink (React for CLIs) and Clack prompts. Contains 42 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
9+
10+
## When to Apply
11+
12+
Reference these guidelines when:
13+
- Building CLI tools with interactive prompts using @clack/prompts
14+
- Creating React-based terminal UIs with Ink
15+
- Handling keyboard input and user interactions
16+
- Optimizing terminal rendering and preventing flicker
17+
- Designing developer-friendly CLI experiences
18+
19+
## Rule Categories by Priority
20+
21+
| Priority | Category | Impact | Prefix |
22+
|----------|----------|--------|--------|
23+
| 1 | Rendering & Output | CRITICAL | `render-` |
24+
| 2 | Input & Keyboard | CRITICAL | `input-` |
25+
| 3 | Component Patterns | HIGH | `tuicomp-` |
26+
| 4 | State & Lifecycle | HIGH | `tuistate-` |
27+
| 5 | Prompt Design | MEDIUM-HIGH | `prompt-` |
28+
| 6 | UX & Feedback | MEDIUM | `ux-` |
29+
| 7 | Configuration & CLI | MEDIUM | `tuicfg-` |
30+
| 8 | Robustness & Compatibility | LOW-MEDIUM | `robust-` |
31+
32+
## Quick Reference
33+
34+
### 1. Rendering & Output (CRITICAL)
35+
36+
- `render-single-write` - Batch Terminal Output in Single Write
37+
- `render-overwrite-dont-clear` - Overwrite Content Instead of Clear and Redraw
38+
- `render-synchronized-output` - Use Synchronized Output Protocol for Animations
39+
- `render-60fps-baseline` - Target 60fps for Smooth Animation
40+
- `render-partial-updates` - Update Only Changed Regions
41+
- `render-escape-sequence-batching` - Defer ANSI Escape Code Generation to Final Output
42+
43+
### 2. Input & Keyboard (CRITICAL)
44+
45+
- `input-useinput-hook` - Use useInput Hook for Keyboard Handling
46+
- `input-immediate-feedback` - Provide Immediate Visual Feedback for Input
47+
- `input-modifier-keys` - Handle Modifier Keys Correctly
48+
- `input-isactive-focus` - Use isActive Option for Focus Management
49+
- `input-escape-routes` - Always Provide Escape Routes
50+
51+
### 3. Component Patterns (HIGH)
52+
53+
- `tuicomp-box-flexbox` - Use Box Component with Flexbox for Layouts
54+
- `tuicomp-text-styling` - Use Text Component for All Visible Content
55+
- `tuicomp-measure-element` - Use measureElement for Dynamic Sizing
56+
- `tuicomp-static-for-logs` - Use Static Component for Log Output
57+
- `tuicomp-percentage-widths` - Use Percentage Widths for Responsive Layouts
58+
- `tuicomp-border-styles` - Use Border Styles for Visual Structure
59+
60+
### 4. State & Lifecycle (HIGH)
61+
62+
- `tuistate-useapp-exit` - Use useApp Hook for Application Lifecycle
63+
- `tuistate-cleanup-effects` - Always Clean Up Effects on Unmount
64+
- `tuistate-functional-updates` - Use Functional State Updates to Avoid Stale Closures
65+
- `tuistate-usecallback-stable` - Stabilize Callbacks with useCallback
66+
- `tuistate-usememo-expensive` - Memoize Expensive Computations with useMemo
67+
68+
### 5. Prompt Design (MEDIUM-HIGH)
69+
70+
- `prompt-group-flow` - Use Clack group() for Multi-Step Prompts
71+
- `prompt-validation` - Validate Input Early with Descriptive Messages
72+
- `prompt-cancellation` - Handle Cancellation Gracefully with isCancel
73+
- `prompt-spinner-tasks` - Use Spinner and Tasks for Long Operations
74+
- `prompt-custom-render` - Build Custom Prompts with @clack/core
75+
76+
### 6. UX & Feedback (MEDIUM)
77+
78+
- `ux-progress-indicators` - Show Progress for Operations Over 1 Second
79+
- `ux-color-semantics` - Use Colors Semantically and Consistently
80+
- `ux-error-messages` - Write Actionable Error Messages
81+
- `ux-next-steps` - Show Next Steps After Completion
82+
- `ux-intro-outro` - Use Intro and Outro for Session Framing
83+
84+
### 7. Configuration & CLI (MEDIUM)
85+
86+
- `tuicfg-sensible-defaults` - Provide Sensible Defaults for All Options
87+
- `tuicfg-env-vars` - Support Standard Environment Variables
88+
- `tuicfg-flags-over-args` - Prefer Flags Over Positional Arguments
89+
- `tuicfg-help-system` - Implement Comprehensive Help System
90+
- `tuicfg-json-output` - Support Machine-Readable Output Format
91+
92+
### 8. Robustness & Compatibility (LOW-MEDIUM)
93+
94+
- `robust-tty-detection` - Detect TTY and Adjust Behavior Accordingly
95+
- `robust-signal-handling` - Handle Process Signals Gracefully
96+
- `robust-exit-codes` - Use Meaningful Exit Codes
97+
- `robust-terminal-restore` - Always Restore Terminal State on Exit
98+
- `robust-graceful-degradation` - Degrade Gracefully for Limited Terminals
99+
100+
## How to Use
101+
102+
Read individual reference files for detailed explanations and code examples:
103+
104+
- [Section definitions](references/_sections.md) - Category structure and impact levels
105+
- [Rule template](assets/templates/_template.md) - Template for adding new rules
106+
- [render-single-write](references/render-single-write.md) - Example rule file
107+
- [input-useinput-hook](references/input-useinput-hook.md) - Example rule file
108+
109+
## Full Compiled Document
110+
111+
For the complete guide with all rules expanded: `AGENTS.md`

0 commit comments

Comments
 (0)