xtrm-tools 2.2.0 → 2.4.0

package/project-skills/tdd-guard/docs/enforcement.md

@@ -1,46 +0,0 @@
-# Strengthening TDD Enforcement
-
-Ensure consistent TDD validation by preventing agents from modifying guard settings or bypassing file operation hooks.
-
-## Protect Guard Settings
-
-Prevent agents from accessing TDD Guard's configuration and state:
-
-```json
-{
-  "permissions": {
-    "deny": ["Read(.claude/tdd-guard/**)"]
-  }
-}
-```
-
-This protects your custom instructions, guard state, and test results from unintended changes.
-
-## Block File Operation Bypass
-
-If your settings allow shell commands without approval, agents can modify files without triggering TDD validation. Block these commands to maintain enforcement:
-
-```json
-{
-  "permissions": {
-    "deny": [
-      "Bash(echo:*)",
-      "Bash(printf:*)",
-      "Bash(sed:*)",
-      "Bash(awk:*)",
-      "Bash(perl:*)"
-    ]
-  }
-}
-```
-
-**Note:** Only needed if you've configured auto-approval for shell commands. May limit some agent capabilities.
-
-## Where to Apply
-
-Add these settings to your chosen settings file. See [Settings File Locations](configuration.md#settings-file-locations) to choose the appropriate location.
-
-## Need Help?
-
-- Report bypass methods: [GitHub Issues](https://github.com/nizos/tdd-guard/issues)
-- Share strategies: [GitHub Discussions](https://github.com/nizos/tdd-guard/discussions)

package/project-skills/tdd-guard/docs/ignore-patterns.md

@@ -1,81 +0,0 @@
-# Ignore Patterns Guide
-
-Configure TDD Guard to skip validation for specific files using glob patterns.
-
-## Why Use Ignore Patterns?
-
-Control exactly which files TDD Guard validates. Useful for monorepos, rapid prototyping, or when different parts of your codebase need different validation rules.
-
-## Default Ignore Patterns
-
-By default, TDD Guard ignores files with these extensions:
-
-- `*.md` - Markdown documentation
-- `*.txt` - Text files
-- `*.log` - Log files
-- `*.json` - JSON configuration files
-- `*.yml` / `*.yaml` - YAML configuration files
-- `*.xml` - XML files
-- `*.html` - HTML files
-- `*.css` - Stylesheets
-- `*.rst` - reStructuredText documentation
-
-## Custom Ignore Patterns
-
-You can configure custom ignore patterns by creating a `config.json` file in the TDD Guard data directory (`.claude/tdd-guard/data/`):
-
-```json
-{
-  "guardEnabled": true,
-  "ignorePatterns": [
-    "*.md",
-    "*.css",
-    "*.json",
-    "*.yml",
-    "**/*.generated.ts",
-    "**/public/**",
-    "*.config.*"
-  ]
-}
-```
-
-**Note**: Custom patterns replace the default patterns entirely. If you want to keep some defaults (like `*.md` or `*.json`), include them in your custom list.
-
-## Pattern Syntax
-
-Patterns use minimatch syntax (similar to `.gitignore`):
-
-- `*.ext` - Match files with extension (e.g., `*.md`)
-- `dir/**` - Match all files in directory (e.g., `dist/**`)
-- `**/*.ext` - Match extension anywhere (e.g., `**/*.test.ts`)
-- `*.{js,ts}` - Match multiple extensions (e.g., `*.{yml,yaml}`)
-- `path/**/*.ext` - Match in specific path (e.g., `src/**/*.spec.js`)
-
-## Managing Patterns
-
-### Viewing Current Patterns
-
-To see which patterns are currently active, check your `config.json` file:
-
-```bash
-cat .claude/tdd-guard/data/config.json
-```
-
-If no custom patterns are configured, the default patterns listed above are used.
-
-### Updating Patterns
-
-1. Create or edit `.claude/tdd-guard/data/config.json`
-2. Add your `ignorePatterns` array
-3. The changes take effect immediately
-
-### Testing Patterns
-
-To verify your patterns work as expected:
-
-1. Edit a file that should be ignored
-2. TDD Guard should skip validation immediately
-
-## Summary
-
-Ignore patterns provide the flexibility to apply TDD validation exactly where you want it in your codebase. Start with the defaults, then customize as your project's needs evolve.

package/project-skills/tdd-guard/docs/linting.md

@@ -1,109 +0,0 @@
-# Linting and Refactoring Support
-
-TDD Guard can optionally check code quality during the refactoring phase (when tests are green) using ESLint.
-When issues are detected, the coding agent will be prompted to fix them.
-
-## Why Use Refactoring Support?
-
-During the TDD green phase, the coding agent may:
-
-- Clean up implementation code
-- Extract methods or constants
-- Improve naming
-- Remove duplication
-
-The refactoring support helps by:
-
-- Running ESLint automatically after file modifications
-- Detecting code quality issues
-- Prompting the coding agent to fix any issues found
-
-## Setup
-
-1. **Install ESLint** in your project:
-
-   ```bash
-   npm install --save-dev eslint@latest
-   ```
-
-2. **Enable linting** by setting the environment variable:
-
-   ```bash
-   LINTER_TYPE=eslint
-   ```
-
-   Note: Currently only ESLint is supported. Additional linters may be added in the future.
-
-3. **Configure the PostToolUse hook**
-
-   You can configure this hook either through the interactive `/hooks` command or by manually editing your settings file. See [Settings File Locations](configuration.md#settings-file-locations) to choose the appropriate location. Use the same location as your PreToolUse hook.
-
-   ### Interactive Setup (Recommended)
-   1. Type `/hooks` in Claude Code
-   2. Select `PostToolUse - After tool execution`
-   3. Choose `+ Add new matcher...`
-   4. Enter: `Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol`
-   5. Select `+ Add new hook...`
-   6. Enter command: `tdd-guard`
-   7. Choose where to save
-
-   ### Manual Configuration
-
-   Add to your chosen settings file:
-
-   ```json
-   {
-     "hooks": {
-       "PostToolUse": [
-         {
-           "matcher": "Write|Edit|MultiEdit|mcp__serena__rename_symbol|mcp__serena__replace_symbol_body|mcp__serena__insert_after_symbol|mcp__serena__insert_before_symbol",
-           "hooks": [
-             {
-               "type": "command",
-               "command": "tdd-guard"
-             }
-           ]
-         }
-       ]
-     }
-   }
-   ```
-
-## How It Works
-
-When enabled:
-
-1. After any file modification (Edit, MultiEdit, Write)
-2. TDD Guard runs ESLint on modified files
-3. If issues are found, the coding agent receives a notification
-4. The agent will then fix the identified issues
-
-Without `LINTER_TYPE=eslint`, TDD Guard skips all linting operations.
-
-**Tip**: Configure ESLint with complexity rules (e.g., `complexity`, `max-depth`) and the SonarJS plugin to encourage meaningful refactoring.
-These rules help identify code that could benefit from simplification during the green phase.
-
-## ESLint Configuration
-
-For effective refactoring support, consider adding these rules to your `.eslintrc.js`:
-
-```javascript
-module.exports = {
-  rules: {
-    complexity: ['warn', 10],
-    'max-depth': ['warn', 4],
-    'max-lines-per-function': ['warn', 50],
-    'max-nested-callbacks': ['warn', 3],
-    'max-params': ['warn', 4],
-  },
-}
-```
-
-## Troubleshooting
-
-### ESLint Not Running
-
-1. Verify ESLint is installed: `npm list eslint`
-2. Check that `LINTER_TYPE=eslint` is set in your `.env` file
-3. Ensure the PostToolUse hook is configured
-4. Restart your Claude session after making changes

package/project-skills/tdd-guard/docs/quick-commands.md

@@ -1,52 +0,0 @@
-# TDD Guard Quick Commands
-
-TDD Guard can be quickly enabled or disabled using simple commands in your Claude Code session.
-This is particularly useful when you need to temporarily disable TDD enforcement during prototyping or exploration phases.
-
-## Usage
-
-Simply type one of these commands in your Claude Code prompt:
-
-- `tdd-guard on` - Enables TDD Guard enforcement
-- `tdd-guard off` - Disables TDD Guard enforcement
-
-The commands are case-insensitive, so `TDD-Guard OFF`, `tdd-guard off`, and `Tdd-Guard Off` all work the same way.
-
-## Setup
-
-To enable the quick commands feature, you need to add the UserPromptSubmit hook to your Claude Code configuration.
-You can set this up either through the interactive `/hooks` command or by manually editing your settings file. See [Settings File Locations](configuration.md#settings-file-locations) to choose the appropriate location.
-
-### Using Interactive Setup (Recommended)
-
-1. Type `/hooks` in Claude Code
-2. Select `UserPromptSubmit - When the user submits a prompt`
-3. Select `+ Add new hook...`
-4. Enter command: `tdd-guard`
-5. Choose where to save
-
-### Manual Configuration (Alternative)
-
-Add the following to your chosen settings file:
-
-```json
-{
-  "hooks": {
-    "userpromptsubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "tdd-guard"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-Note: Your configuration file may already have other hooks configured.
-Simply add the `userpromptsubmit` section to your existing hooks object.
-
-**Tip**: To prevent agents from modifying the TDD Guard state, see [Strengthening TDD Enforcement](enforcement.md).

package/project-skills/tdd-guard/docs/session-management.md

@@ -1,75 +0,0 @@
-# TDD Guard Session Management
-
-The SessionStart hook manages TDD Guard's session data and ensures a clean slate for each Claude Code session.
-
-## What It Does
-
-### Clears Transient Data
-
-- Test results from previous sessions
-- Lint reports and code quality checks
-- Other temporary validation data
-
-### Sets Up Validation Rules
-
-- Creates the customizable instructions file if it doesn't exist
-- Preserves your custom rules if already configured
-- See [Custom Instructions](custom-instructions.md) for details
-
-**Note:** The guard's enabled/disabled state is preserved across sessions.
-
-## Setup
-
-To enable session management, you need to add the SessionStart hook to your Claude Code configuration.
-You can set this up either through the interactive `/hooks` command or by manually editing your settings file. See [Settings File Locations](configuration.md#settings-file-locations) to choose the appropriate location.
-
-### Using Interactive Setup (Recommended)
-
-1. Type `/hooks` in Claude Code
-2. Select `SessionStart - When a new session is started`
-3. Select `+ Add new matcher…`
-4. Enter matcher: `startup|resume|clear`
-5. Select `+ Add new hook…`
-6. Enter command: `tdd-guard`
-7. Choose where to save
-
-### Manual Configuration (Alternative)
-
-Add the following to your chosen settings file:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup|resume|clear",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "tdd-guard"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-Note: Your configuration file may already have other hooks configured.
-Simply add the `SessionStart` section to your existing hooks object.
-
-## How It Works
-
-The SessionStart hook triggers when:
-
-- Claude Code starts up (`startup`)
-- A session is resumed (`resume`)
-- The `/clear` command is used (`clear`)
-
-When triggered, TDD Guard clears all transient data while preserving the guard state and your custom validation rules.
-
-## Tips
-
-- No manual intervention needed - clearing happens automatically
-- To toggle the guard on/off, use the [quick commands](quick-commands.md)
-- For debugging, check `.claude/tdd-guard/` to see stored data

package/project-skills/tdd-guard/docs/storybook-vitest-addon.md

@@ -1,120 +0,0 @@
-# Storybook with Vitest Addon
-
-If you're using Storybook 10+ with a Vite-based framework, you can use `@storybook/addon-vitest` instead of `@storybook/test-runner`. This approach uses TDD Guard's existing Vitest reporter to capture Storybook test results.
-
-## Why Use the Vitest Addon?
-
-The Vitest addon offers several advantages:
-
-- **Faster execution** - Uses Vitest's browser mode instead of Playwright
-- **Modern tooling** - Built on Vitest, which is faster and more modern than Jest
-- **Unified testing** - Run Storybook tests alongside your other Vitest tests
-- **Better DX** - Full Storybook Test experience with interaction, accessibility, and visual tests
-- **Simpler setup** - Uses your existing Vitest configuration
-
-## Requirements
-
-- Storybook 10+
-- Vite-based Storybook framework (React-Vite, Vue-Vite, Svelte-Vite, etc.)
-- Vitest
-
-## Setup
-
-### 1. Install the Vitest Addon
-
-```bash
-npm install --save-dev @storybook/addon-vitest
-```
-
-### 2. Configure Storybook
-
-Add the addon to your `.storybook/main.ts`:
-
-```typescript
-import type { StorybookConfig } from '@storybook/react-vite'
-
-const config: StorybookConfig = {
-  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
-  addons: ['@storybook/addon-vitest'],
-  framework: '@storybook/react-vite',
-}
-
-export default config
-```
-
-### 3. Configure Vitest Reporter
-
-Since the Vitest addon runs your Storybook tests through Vitest, you use the `tdd-guard-vitest` reporter to capture results:
-
-```bash
-npm install --save-dev tdd-guard-vitest
-```
-
-Add to your `vitest.config.ts`:
-
-```typescript
-import { defineConfig } from 'vitest/config'
-import { VitestReporter } from 'tdd-guard-vitest'
-
-export default defineConfig({
-  test: {
-    reporters: [
-      'default',
-      new VitestReporter('/Users/username/projects/my-app'),
-    ],
-  },
-})
-```
-
-### 4. Run Tests
-
-```bash
-npm run test
-```
-
-Your Storybook interaction tests will run alongside your regular Vitest tests, and TDD Guard will capture all results.
-
-## Comparison with Test Runner
-
-| Feature            | @storybook/test-runner | @storybook/addon-vitest |
-| ------------------ | ---------------------- | ----------------------- |
-| Test framework     | Jest + Playwright      | Vitest browser mode     |
-| Storybook version  | 6.4+                   | 10+                     |
-| Framework support  | All frameworks         | Vite-based only         |
-| TDD Guard reporter | tdd-guard-storybook    | tdd-guard-vitest        |
-| Speed              | Slower (full browser)  | Faster                  |
-
-## When to Use Each
-
-**Use `@storybook/addon-vitest` when:**
-
-- You're on Storybook 10+
-- You're using a Vite-based framework
-- You want faster test execution
-- You want to unify your testing setup
-
-**Use `@storybook/test-runner` when:**
-
-- You're on Storybook 6.4-9.x
-- You need Webpack-based framework support
-- You need full Playwright browser testing
-
-## Troubleshooting
-
-### Tests Not Running
-
-1. Verify Storybook is configured with the Vitest addon
-2. Check that your stories have `play` functions (interaction tests)
-3. Ensure `tdd-guard-vitest` is in your Vitest reporters
-
-### Results Not Captured
-
-1. Verify `tdd-guard-vitest` is installed and configured
-2. Check the project root path is correct in the reporter config
-3. Look for `.claude/tdd-guard/data/test.json` after running tests
-
-## Further Reading
-
-- [Storybook Vitest Addon Documentation](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon)
-- [Vitest Reporter Configuration](../reporters/vitest/README.md)
-- [TDD Guard Configuration](configuration.md)

package/project-skills/tdd-guard/docs/validation-model.md

@@ -1,63 +0,0 @@
-# Validation Model Configuration
-
-TDD Guard validates changes using AI. Configure both the validation client (SDK or API) and the Claude model version.
-
-## Claude Agent SDK (Default)
-
-The recommended approach. Uses the Claude Agent SDK to communicate with Claude directly.
-
-```bash
-VALIDATION_CLIENT=sdk  # Default, can be omitted
-```
-
-**Features:**
-
-- Works automatically with your Claude Code installation
-- Uses your Claude Code subscription (no extra charges)
-- Requires Claude Code to be installed and authenticated
-
-**Important:** If you have `ANTHROPIC_API_KEY` set in your environment, Claude Code may use it for billing instead of your subscription. To avoid unexpected charges:
-
-```bash
-# Check if API key is set
-echo $ANTHROPIC_API_KEY
-
-# Unset it if present
-unset ANTHROPIC_API_KEY
-```
-
-If you've never created an API key, you can ignore this warning.
-
-## Anthropic API
-
-For CI/CD environments or when you need faster validation. Requires separate billing from Claude Code.
-
-```bash
-VALIDATION_CLIENT=api
-TDD_GUARD_ANTHROPIC_API_KEY=your_api_key_here
-```
-
-Get your API key from [console.anthropic.com](https://console.anthropic.com/)
-
-**Notes:**
-
-- Charges separately from your Claude Code subscription ([pricing](https://www.anthropic.com/pricing))
-- We use `TDD_GUARD_ANTHROPIC_API_KEY` (not `ANTHROPIC_API_KEY`) to prevent accidental charges. If you used the regular `ANTHROPIC_API_KEY`, Claude Code might use it for all your normal coding tasks, charging your API account instead of using your subscription.
-
-## Model Selection
-
-Configure which Claude model to use for validation (default: `claude-sonnet-4-0`):
-
-```bash
-# Fastest but unreliable results
-TDD_GUARD_MODEL_VERSION=claude-3-5-haiku-20241022
-
-# Best results but slowest
-TDD_GUARD_MODEL_VERSION=claude-opus-4-1
-```
-
-See [Claude model overview](https://docs.anthropic.com/en/docs/about-claude/models/overview) for available models and pricing. Note: pricing only applies to API users - SDK uses your Claude Code subscription by default. Balance model capability with [custom instructions](custom-instructions.md) to optimize for your needs.
-
-## Migration from Legacy Configuration
-
-If you're using the old `MODEL_TYPE` configuration, see the [Configuration Migration Guide](config-migration.md) for detailed instructions.

package/project-skills/tdd-guard/eslint.config.mjs

@@ -1,140 +0,0 @@
-import js from '@eslint/js'
-import typescript from '@typescript-eslint/eslint-plugin'
-import typescriptParser from '@typescript-eslint/parser'
-import sonarjs from 'eslint-plugin-sonarjs'
-import globals from 'globals'
-
-export default [
-  js.configs.recommended,
-  {
-    files: ['**/*.{ts,tsx}'],
-    languageOptions: {
-      parser: typescriptParser,
-      parserOptions: {
-        ecmaVersion: 2020,
-        sourceType: 'module',
-        project: './tsconfig.eslint.json',
-      },
-      globals: {
-        ...globals.es2020,
-        ...globals.node,
-      },
-    },
-    plugins: {
-      '@typescript-eslint': typescript,
-      sonarjs: sonarjs,
-    },
-    rules: {
-      ...typescript.configs.recommended.rules,
-      ...sonarjs.configs.recommended.rules,
-
-      // Prettier handling
-      'no-extra-semi': 'off',
-      semi: 'off',
-
-      // === COMPLEXITY & SIZE ===
-      complexity: ['error', 20],
-      'sonarjs/cognitive-complexity': ['error', 20],
-      'max-lines-per-function': ['warn', 80],
-      'max-depth': ['error', 5],
-      'max-nested-callbacks': ['error', 5],
-      'max-params': ['warn', 5],
-      'max-statements': ['warn', 40],
-      'sonarjs/max-switch-cases': ['error', 30],
-
-      // === CODE DUPLICATION ===
-      'sonarjs/no-duplicate-string': ['error', { threshold: 5 }],
-      'sonarjs/no-identical-functions': 'error',
-      'sonarjs/no-duplicated-branches': 'error',
-      'sonarjs/no-identical-conditions': 'error',
-      'sonarjs/no-identical-expressions': 'error',
-
-      // === CODE QUALITY & SMELLS ===
-      'no-magic-numbers': [
-        'warn',
-        {
-          ignore: [0, 1, -1, 2, 100],
-          ignoreArrayIndexes: true,
-          enforceConst: true,
-        },
-      ],
-      'sonarjs/no-redundant-boolean': 'error',
-      'sonarjs/no-redundant-jump': 'error',
-      'sonarjs/no-redundant-assignments': 'error',
-      'sonarjs/no-small-switch': 'error',
-      'sonarjs/prefer-immediate-return': 'error',
-      'sonarjs/no-inverted-boolean-check': 'error',
-      'sonarjs/no-gratuitous-expressions': 'error',
-      'sonarjs/no-unthrown-error': 'error',
-      'sonarjs/prefer-object-literal': 'error',
-      'sonarjs/todo-tag': 'off', // We have items called todo
-
-      // === STRUCTURE & READABILITY ===
-      'sonarjs/no-collapsible-if': 'error',
-      'sonarjs/no-nested-switch': 'error',
-      'sonarjs/no-nested-template-literals': 'error',
-      'sonarjs/no-same-line-conditional': 'error',
-      'no-nested-ternary': 'error',
-      'no-else-return': 'error',
-
-      // === MAINTAINABILITY ===
-      'sonarjs/no-collection-size-mischeck': 'error',
-      'sonarjs/no-unused-vars': 'error',
-      'sonarjs/no-unused-function-argument': 'error',
-      'no-shadow': 'error',
-      'no-param-reassign': 'error',
-      // 'consistent-return': 'error',
-
-      // === MODERN JAVASCRIPT ===
-      'prefer-const': 'error',
-      'prefer-template': 'error',
-      'object-shorthand': 'error',
-      'prefer-arrow-callback': 'error',
-      'prefer-object-spread': 'error',
-
-      // === TYPESCRIPT SPECIFIC ===
-      '@typescript-eslint/explicit-function-return-type': 'warn',
-      '@typescript-eslint/no-explicit-any': 'error',
-      '@typescript-eslint/prefer-readonly': 'error',
-      '@typescript-eslint/prefer-optional-chain': 'error',
-      '@typescript-eslint/prefer-nullish-coalescing': 'error',
-      '@typescript-eslint/no-unnecessary-condition': 'warn',
-      '@typescript-eslint/switch-exhaustiveness-check': 'error',
-      'sonarjs/use-type-alias': 'warn',
-      'sonarjs/redundant-type-aliases': 'error',
-    },
-  },
-  {
-    files: [
-      '**/*.test.ts',
-      '**/*.spec.ts',
-      '**/*.test.tsx',
-      '**/*.spec.tsx',
-      '**/factories/*',
-    ],
-    rules: {
-      'max-lines-per-function': 'off',
-      'sonarjs/no-nested-functions': 'off',
-      'no-magic-numbers': 'off',
-      complexity: ['error', 20],
-      'sonarjs/cognitive-complexity': ['error', 20],
-      'max-nested-callbacks': ['error', 10],
-      '@typescript-eslint/explicit-function-return-type': 'off',
-      'sonarjs/no-duplicate-string': ['error', { threshold: 20 }],
-    },
-  },
-  {
-    ignores: [
-      '**/dist/**',
-      '**/node_modules/**',
-      'coverage/**',
-      '**/artifacts/**',
-      '.venv/**',
-      'reporters/pytest/**',
-      'reporters/phpunit/**',
-      'reporters/go/**',
-      '**/*.d.ts',
-      '**/*.tsbuildinfo',
-    ],
-  },
-]