tui-cli

Ensures TUI+CLI+Documentation parity for all feature changes. CRITICAL - Use this for EVERY change that affects commands, screens, shortcuts, or settings. Validates that changes are reflected in TUI implementation, CLI commands, docs/cli/, docs/tui/, docs/tui/shortcuts.md, CLAUDE.md, and feature registry. Prevents documentation drift and missing implementations.

⭐2stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026

When & Why to Use This Skill

The TUI+CLI Parity Enforcer is a specialized developer tool designed to maintain absolute synchronization between a project's Terminal User Interface (TUI), Command Line Interface (CLI), and all associated documentation. By automating the detection of feature changes and extracting command metadata directly from source code, it ensures that documentation like CLAUDE.md, README.md, and specific CLI/TUI guides remain accurate, preventing documentation drift and ensuring a seamless user experience across all interfaces.

Use Cases

  • Synchronizing CLI flags and options with TUI keyboard shortcuts and screens after implementing new features to ensure interface consistency.
  • Automatically updating technical documentation and Markdown help files when command-line arguments or descriptions are modified in the TypeScript source code.
  • Generating customized verification checklists for developers during the PR process to ensure three-way parity between business logic, user interfaces, and documentation.
  • Validating that every user-facing change is correctly reflected in the feature registry and quick-reference guides to prevent missing implementations or outdated manuals.
nametui-cli
descriptionEnsures TUI+CLI+Documentation parity for all feature changes. CRITICAL - Use this for EVERY change that affects commands, screens, shortcuts, or settings. Validates that changes are reflected in TUI implementation, CLI commands, docs/cli/, docs/tui/, docs/tui/shortcuts.md, CLAUDE.md, and feature registry. Prevents documentation drift and missing implementations.

TUI + CLI + Documentation Parity Enforcer

⚠️ CRITICAL USAGE: This skill MUST be invoked for EVERY change that affects:

  • Commands (CLI or TUI)
  • Keyboard shortcuts
  • Screens or UI elements
  • Settings or configuration
  • Feature additions/modifications

Core Principle

Every feature in this project requires three-way parity:

  1. TUI Implementation - Interactive terminal UI with keyboard shortcuts
  2. CLI Implementation - Command-line interface with flags and options
  3. Documentation - Multiple doc files must stay synchronized

Missing any one = broken user experience.

How It Works

The skill:

  1. Detects your branch - If on a feature branch, compares with main; if on main, shows staged/unstaged changes
  2. Maps changed files - Groups modifications by feature type (CLI commands, TUI screens, shared logic, etc.)
  3. Extracts command info - Parses new/modified CLI commands from TypeScript files
  4. Updates documentation - Automatically updates docs/cli/, docs/tui/, CLAUDE.md, and README.md with new commands and features
  5. Generates checklists - Creates customized verification items for each affected feature
  6. Filters noise - Ignores config files (package.json, package-lock.json) and re-export index files

Usage

Run the analysis script to generate your parity checklist and update documentation:

python3 .claude/skills/tui-cli/scripts/generate_checklist.py

Output includes:

  • 🌿 Current branch info
  • 🔍 Number of source files modified across features
  • 📦 Configuration/dependency files (listed separately)
  • 📚 Documentation files that were updated
  • Feature-grouped file list
  • Customized parity checklist for each feature

Documentation Update Map

The skill automatically updates documentation based on file changes:

Changed File Documentation Updates
src/cli/commands/*.cmd.ts docs/cli/<category>.md, CLAUDE.md (CLI Commands section), README.md
src/tui/screens/*.screen.ts docs/tui/screens.md, docs/tui/overview.md
src/tui/index.ts docs/tui/shortcuts.md, docs/tui/overview.md
src/services/*.service.ts (No direct doc update, but noted in parity checklist)
src/shared/features.ts (Feature registry validation in checklist)

Documentation File Formats

docs/cli/<category>.md

Each command category has its own file with:

  • Command heading: ## <command-name>
  • Description paragraph
  • Usage block: ```bash\nmcpsm <command> [options]\n```
  • Options table with pipes: | Option | Description |
  • Examples with code blocks
  • Output samples (where applicable)

docs/tui/screens.md

Lists all TUI screens with:

  • Screen name
  • Description
  • Key bindings/navigation
  • Features available

docs/tui/shortcuts.md

Keyboard shortcuts reference with:

  • Shortcut key(s)
  • Action description
  • Context/screen where applicable

CLAUDE.md (CLI Commands section)

Quick reference format:

mcpsm command [args]     Brief description
mcpsm command2 <param>   Another description

README.md

  • Main feature highlights
  • Common commands (top-level only)
  • Links to full documentation

Feature Detection Map

The skill recognizes these file patterns:

src/cli/commands/        → CLI Command Implementation
src/tui/screens/         → TUI Screen Implementation
src/tui/index.ts         → TUI Main Screen/Key Bindings
src/services/*.ts        → Shared Business Logic
src/shared/features.ts   → Feature Registry
tests/                   → Test Coverage

Parity Checklist Items

For each modified feature, you'll verify:

1. Shared Logic

  • Business logic in src/services/
  • Function exported for CLI + TUI use
  • I/O separated from core logic

2. CLI Implementation

  • Command in src/cli/commands/
  • Supports --json flag if applicable
  • Supports -y/--force if applicable

3. TUI Implementation

  • Screen/handler in src/tui/
  • Keyboard shortcuts documented
  • State management consistent with CLI

4. Feature Registry

  • Updated src/shared/features.ts
  • Defines id, name, category
  • Lists cliCommands and tuiImplementation

5. Documentation

  • CLI commands documented in docs/cli/<category>.md
  • New options documented with descriptions and examples
  • TUI screens documented in docs/tui/screens.md (if applicable)
  • Quick reference in CLAUDE.md updated
  • README.md updated if feature is user-facing

6. Testing

  • Run npm test for parity verification
  • Feature in both CLI and TUI
  • Behavior consistent across interfaces

Instructions for Claude When Updating Documentation

When this skill detects CLI/TUI changes, Claude will:

1. Parse CLI Commands

Extract from TypeScript files (src/cli/commands/*.cmd.ts):

  • Command name - From .command("name [args]")
  • Aliases - From .aliases([...])
  • Description - From .description("...")
  • Options - From .option("--flag <value>", "description")
  • Examples - Comment-based or inferred from usage patterns

Example extraction from TypeScript:

program
  .command("test [server]")
  .description("Test MCP server health and tools")
  .option("--json", "Output in JSON format")
  .option("-v, --verbose", "Verbose output")
  .action(async (server, options) => {
    // implementation
  });

Becomes in documentation:

## test

Test MCP server health and tools.

### Usage

\`\`\`bash
mcpsm test [server] [options]
\`\`\`

### Options

| Option          | Description                                |
| --------------- | ------------------------------------------ |
| `[server]`      | Server name to test (tests all if omitted) |
| `--json`        | Output in JSON format                      |
| `-v, --verbose` | Verbose output                             |

### Examples

\`\`\`bash

# Test a specific server

mcpsm test my-server

# Test all servers with verbose output

mcpsm test --verbose
\`\`\`

2. Update Documentation Files

For docs/cli/<category>.md:

  • Keep existing commands, update modified ones
  • Add new commands maintaining the format
  • Preserve all explanatory text and examples
  • Use horizontal rule --- between commands

For CLAUDE.md (CLI Commands section):

  • Update quick reference: mcpsm command [args] Description
  • Keep format consistent with existing commands
  • Maintain alphabetical order within sections

For README.md:

  • Update highlights if major new feature
  • Link to documentation files
  • Keep user-friendly language

3. Preservation Rules

  • Never remove commands from documentation (mark as deprecated if needed)
  • Always preserve existing examples and explanations
  • Maintain formatting - Don't change markdown styles
  • Keep order - Don't reorder existing commands

4. Validation

  • Use npm run lint to verify formatting
  • Test documentation formatting: open generated .md files
  • Verify command syntax matches actual implementation

Example Output

On main branch with no changes:

✅ No changes detected - nothing needs to be done

On feature branch with CLI + TUI changes:

🌿 Current branch: matt/implement-gateway

🔍 Detected 5 source file(s) across 3 feature(s)
📦 Also modified: `package-lock.json`, `package.json` (config/deps)

📚 Documentation Updates:
   ✅ docs/cli/daemon.md - Updated 2 commands
   ✅ docs/tui/screens.md - Added DaemonScreen
   ✅ CLAUDE.md - Updated CLI Commands section
   ✅ README.md - Updated feature list

### Modified Files by Feature

**DAEMON**
  - [CLI] src/cli/commands/daemon.cmd.ts

**DAEMONSCREEN**
  - [TUI] src/tui/screens/DaemonScreen.tsx
  - [TUI] tests/tui/screens/DaemonScreen.test.tsx

**GATEWAY**
  - [Logic] src/services/gateway.service.ts

### Parity Checklist

[Customized checklist for each feature...]

- [x] CLI commands documented
- [x] TUI screens documented
- [x] Quick reference updated
- [ ] README highlights updated (if needed)