@xonovex/skills 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "xonovex",
+  "description": "Xonovex coding guidelines and workflow skills for Claude Code",
+  "version": "0.1.0",
+  "author": {
+    "name": "Xonovex"
+  },
+  "homepage": "https://github.com/xonovex/platform/tree/main/packages/plugins/skills",
+  "repository": "https://github.com/xonovex/platform",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "skills",
+    "guidelines",
+    "typescript",
+    "react",
+    "docker",
+    "kubernetes",
+    "terraform"
+  ]
+}

package/commands/code-align.md

@@ -0,0 +1,108 @@
+---
+description: Create alignment between two similar implementations and suggest improvements
+model: sonnet
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - TaskCreate
+  - TaskUpdate
+  - AskUserQuestion
+argument-hint: "[file1] [file2] [--interactive] [--fix]"
+---
+
+# /code-align – Research Code Alignment Between Similar Implementations
+
+Analyzes two similar implementations to identify structural differences, inconsistencies, and opportunities for alignment. Generates a detailed research report. Does NOT create plans or make changes - run `/plan-create` afterward to create an implementation plan.
+
+## Usage
+
+```bash
+/code-align src/file-a.ts src/file-b.ts
+/code-align src/file-a.ts src/file-b.ts --interactive
+/code-align "src/process-*.ts"
+```
+
+## Arguments
+
+- `file1` (required): Path to first file, or glob pattern
+- `file2` (optional): Path to second file. If omitted and file1 is a glob, compares first two matches
+- `--interactive` (optional): Ask clarifying questions about reference implementation
+
+## Core Workflow
+
+**Use Task agents with subagent_type=Explore and model=haiku for codebase analysis. Do NOT use EnterPlanMode.**
+
+1. **Discovery & Loading**
+   - Resolve files from paths or glob patterns
+   - Read both file contents
+   - Detect code type (API route, processor, etc.)
+
+2. **Structural Analysis** - Compares:
+   - Imports & dependencies: matching imports, missing imports, import order
+   - Interfaces & types: definitions, properties, type consistency
+   - Functions & exports: signatures, helpers, parameters
+   - Code structure: control flow, error handling, logging, naming
+   - Logic & algorithms: processing logic, edge cases, bugs
+   - Configuration: default values, constants
+
+3. **Alignment Report** - Generates:
+   - Summary: Alignment percentage
+   - Critical Differences: Bug-causing issues
+   - Structural Differences: Inconsistent patterns
+   - Missing Features: Functionality in one but not other
+   - Recommendations: Prioritized changes
+
+Example output:
+
+```
+=== Alignment Report ===
+Overall Alignment: 72% aligned
+
+Critical Differences:
+  [X] File2 missing error handling in process() function
+  [X] File1 uses deprecated API vs File2 modern approach
+
+Structural Differences:
+  [WARN]  Different control flow (if/else vs switch)
+  [WARN]  Different logging (console.log vs logger.info)
+  [WARN]  Inconsistent defaults (maxItems: 100 vs 200)
+
+Missing Features:
+  [+] File1 has metrics tracking
+  [+] File2 has deduplication logic
+
+Recommendations:
+  1. Add error handling to File2
+  2. Align logging approach
+  3. Standardize control flow
+  4. Sync configuration values
+```
+
+4. **Interactive Mode** (`--interactive`): Asks questions about reference implementation, control flow preference, default values, missing features
+
+## Examples
+
+```bash
+# Compare two implementations
+/code-align src/process-a.ts src/process-b.ts
+
+# Interactive with glob pattern
+/code-align "src/handler-*.ts" --interactive
+```
+
+## Next Steps
+
+After running this research command:
+
+1. Review the alignment report for accuracy
+2. Run `/plan-create` to create an implementation plan from this research
+
+## Error Handling
+
+- File not found: Verify paths exist
+- Invalid glob: Check pattern syntax
+- Parse errors: Ensure valid TypeScript/JavaScript
+- Validation failures: Review changes, fix test/lint errors

package/commands/code-harden.md

@@ -0,0 +1,74 @@
+---
+description: "Harden code by improving type safety, validation, logging, and error handling"
+model: sonnet
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - Task
+  - TaskCreate
+  - TaskUpdate
+  - AskUserQuestion
+argument-hint: "[path] [--aspects <type-safety,logging,validation>] [--auto-fix] [--dry-run]"
+---
+
+# /code-harden – Research Code Hardening Opportunities
+
+Analyzes code for hardening opportunities (type safety, validation, logging, error handling). Generates a detailed research report. Does NOT create plans or make changes - run `/plan-create` afterward to create an implementation plan.
+
+## Goal
+
+- Identify code quality issues (type safety, logging, validation, best practices, code smells)
+- Apply fixes aligned with project standards
+- Validate changes with typecheck, lint, and tests
+
+## Usage
+
+```bash
+# Analyze all aspects
+/code-harden packages/myapp/
+
+# Focus on specific aspects
+/code-harden src/ --aspects type-safety,logging
+
+# Preview analysis
+/code-harden . --dry-run
+```
+
+## Arguments
+
+- `path` (required): Directory to analyze
+- `--aspects` (optional): Comma-separated aspects (type-safety, logging, validation, error-handling, testing, or custom)
+- `--auto-fix` (optional): Automatically apply safe fixes
+- `--dry-run` (optional): Report issues without making changes
+
+## Core Workflow
+
+**Use Task agents with subagent_type=Explore and model=haiku for codebase analysis. Do NOT use EnterPlanMode.**
+
+1. **Read Guidelines**: Check CLAUDE.md, POLICY.md, AGENTS.md and referenced guidelines for project standards
+2. **Analyze**: Use Task agent with subagent_type=Explore and model=haiku to find anti-patterns and violations; categorize by priority
+3. **Report**: Generate detailed report of issues found, grouped by package and priority
+
+## Implementation Details
+
+**Find guidelines**: Look for CLAUDE.md, POLICY.md, AGENTS.md in project root and subdirectories; check @-referenced documents
+
+**Apply standards**: Follow project-specific patterns from guidelines for type safety, logging, validation, error handling
+
+**Validation**: Fix one package at a time; validate immediately after each
+
+## Error Handling
+
+- **Lint failures**: Review fix against project linting rules; adjust to match standards
+- **Test failures**: Review logic errors, validation strictness, mock compatibility
+- **Type errors**: Check imports, type definitions, schema alignment
+- **Guidelines not found**: Search for coding standards documentation; use language/framework best practices
+
+## Next Steps
+
+After running this research command:
+
+1. Review the hardening report for accuracy
+2. Run `/plan-create` to create an implementation plan from this research

package/commands/code-simplify.md

@@ -0,0 +1,145 @@
+---
+description: >-
+  Simplify code by consolidating duplicates, removing dead code, and flattening
+  abstractions
+model: sonnet
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - TaskCreate
+  - TaskUpdate
+  - AskUserQuestion
+argument-hint: >-
+  [path] [--aspects
+  <duplicates,dead-code,dependencies,abstractions,interfaces,config>]
+  [--dry-run] [--fix]
+---
+
+# /code-simplify – Research Code Simplification Opportunities
+
+Analyzes code complexity to identify consolidation, dead code removal, and simplification opportunities. Generates a detailed research report. Does NOT create plans or make changes - run `/plan-create` afterward to create an implementation plan.
+
+## Goal
+
+- Consolidate duplicated logic into shared utilities
+- Remove unused code, imports, and dependencies
+- Flatten over-engineered abstractions
+- Simplify complex interfaces
+- Centralize scattered configuration
+
+## Usage
+
+```bash
+/code-simplify packages/my-package/
+/code-simplify src/ --aspects duplicates,dead-code
+/code-simplify . --dry-run
+```
+
+## Arguments
+
+- `path` (required): Directory to analyze
+- `--aspects` (optional): Aspects to check (comma-separated):
+  - `duplicates` - Identical/near-identical functions
+  - `utilities` - Logic for shared utilities
+  - `types` - Redundant type definitions
+  - `constants` - Scattered magic values
+  - `patterns` - Repeated code patterns
+  - `dead-code` - Unused functions, unreachable branches
+  - `dependencies` - Unused imports, redundant packages
+  - `abstractions` - Over-engineered patterns
+  - `interfaces` - Complex APIs (>5 params, nested config)
+  - `config` - Scattered configuration
+  - `all` (default) - All aspects
+- `--dry-run` (optional): Report without changes
+
+## Core Workflow
+
+**Use Task agents with subagent_type=Explore and model=haiku for codebase analysis. Do NOT use EnterPlanMode.**
+
+1. **Discovery** - Use Task/Explore agents to scan files, build signature index, analyze dependency trees
+2. **Analysis** - Check each aspect for issues using Explore agents
+3. **Report** - Group by priority, estimate impact, generate detailed report
+
+## Analysis Aspects
+
+**Duplicates**: Same function in multiple files, identical logic with different names, copy-paste blocks (>10 lines)
+
+**Utilities**: Helpers used in multiple places, repeated validation/transformation logic
+
+**Types**: Same interface in multiple files, similar types to unify
+
+**Constants**: Repeated hardcoded values, duplicated config, copied regex patterns
+
+**Patterns**: Duplicated error handling, logging, response formatting
+
+**Dead Code**: Uncalled functions, unreachable branches, unused exports/variables
+
+**Dependencies**: Unused imports, packages not referenced, transitive deps, duplicate functionality
+
+**Abstractions**: Single-implementation interfaces, wrapper classes, single-type factories, deep inheritance (>3 levels)
+
+**Interfaces**: Functions with >5 params, deeply nested config, rarely-used optionals, inconsistent signatures
+
+**Config**: Scattered env access, duplicate defaults, duplicated feature flags/URLs
+
+## Output Format
+
+```
+=== Code Simplification Report ===
+Path: packages/example/
+
+DUPLICATES (8)
+  HIGH: makeNullable() - 6 implementations -> utils/type-modifiers.ts
+  HIGH: inferType() - 4 implementations -> utils/inference.ts
+
+DEAD CODE (12)
+  HIGH: legacyParser() never called - src/parsers/legacy.ts:45
+  MEDIUM: unreachable else - src/handlers/process.ts:89
+
+UNUSED DEPENDENCIES (5)
+  HIGH: lodash -> use optional chaining
+  MEDIUM: moment.js -> already have date-fns
+
+OVER-ENGINEERING (3)
+  HIGH: IRepository (1 impl) -> inline implementation
+  MEDIUM: ConfigFactory (1 type) -> use constructor
+
+Impact: ~450 lines removed, 3 dependencies pruned, 25% complexity reduction
+```
+
+## Implementation Details
+
+**Finding issues**: Grep for signatures, Task agent with subagent_type=Explore and model=haiku for semantic analysis, trace exports, check call graphs
+
+**Location strategy**:
+
+- Same package: `utils/` subdirectory
+- Cross-package: Existing `shared-*` or propose new
+- Follow project conventions
+
+**Safe changes**: Identical implementations, unused imports, single-impl interfaces, constant consolidation
+
+**Validation**: Fix incrementally, validate after each (typecheck/lint/test)
+
+## Error Handling
+
+- **False positives**: Check dynamic imports, reflection, external entry points
+- **Breaking changes**: Ensure no external consumers
+- **Circular deps**: Restructure or create intermediate module
+
+## Examples
+
+```bash
+/code-simplify packages/api/ --aspects dead-code --dry-run
+/code-simplify services/ --aspects abstractions,interfaces
+```
+
+## Next Steps
+
+After running this research command:
+
+1. Review the simplification report for accuracy
+2. Run `/plan-create` to create an implementation plan from this research

package/commands/git-commit.md

@@ -0,0 +1,146 @@
+---
+description: Commit and push changes in the current or a specified directory
+model: haiku
+allowed-tools:
+  - Bash
+  - Read
+argument-hint: >-
+  [message] [--type <feat|fix|docs|chore|refactor|test|ci>] [--path <path>]
+  [--remote <remote>] [--branch <branch>] [--push] [--dry-run] [--interactive]
+---
+
+# /git-commit – Auto-Commit with Smart Messages
+
+Commits changes in a directory with conventional commit format. Automatically generates commit messages based on changed files and plan context.
+
+## Goal
+
+- Auto-commit changes with conventional format
+- Auto-generate messages from changed files and plan context
+- Support interactive mode and optional push
+
+## Arguments
+
+`/git-commit [message] [--type <type>] [--path <path>] [--remote <remote>] [--branch <branch>] [--push] [--dry-run] [--interactive]`
+
+- `message` (optional): Commit description (if omitted, auto-generates and uses best suggestion)
+- `--type <type>` (optional): Commit type (auto-detected if not provided)
+- `--path` (optional): Directory path for git commands (defaults to current directory)
+- `--remote` (optional): Git remote to push to (defaults to "origin")
+- `--branch` (optional): Remote branch to push to (defaults to current branch)
+- `--push` (optional): Push after committing
+- `--dry-run` (optional): Preview without committing
+- `--interactive` (optional): Show suggestions and prompt for selection instead of auto-committing
+
+## Core Workflow
+
+**IMPORTANT: Always auto-commit immediately without prompting. Never ask the user to select a suggestion unless `--interactive` flag is explicitly provided.**
+
+1. **Navigate**: Change to specified `--path` (if provided)
+2. **Check Status**: Detect uncommitted changes and unpushed commits
+3. **Analyze Changes**: Examine changed files to determine type and message
+4. **Generate Message**: Pick the best commit message automatically
+5. **Commit Immediately**: Stage and commit without asking - do NOT show suggestions or ask for confirmation
+6. **Push**: Optionally push to specified remote and branch
+
+Exception: Only show suggestions and prompt for selection when `--interactive` flag is explicitly provided.
+
+## Smart Suggestion Logic
+
+**Type Detection** – Analyze changed files:
+
+- `test`: `*.test.ts`, `*.spec.ts`
+- `docs`: `*.md` in docs/
+- `ci`: CI config files
+- `chore`: `package.json`, config files
+- `feat`: New files in `src/`
+- `fix`: Small modifications in `src/`
+- `refactor`: Large changesets
+
+**Message Generation** – Based on:
+
+1. File patterns (extract package/feature names)
+2. Diff stats (gauge scope)
+3. Plan context (from git config)
+4. Common operations (add/update/fix/remove)
+
+## Implementation Steps
+
+1. **Change Directory**: `cd <path>` (if `--path` specified)
+2. **Check Git Status**: `git status --porcelain` for changes
+3. **Analyze Changes** (if no message provided):
+   - Run: `git diff --stat HEAD`, `git status --porcelain`
+   - Detect type from file patterns
+   - Generate the best commit message
+4. **If Message Provided**: Use directly (skip generation)
+5. **Determine Type**:
+   - Use `--type` if provided
+   - Use detected type from file analysis
+   - Default to "chore"
+6. **Commit Immediately**: `git add -A && git commit -m "<type>: <message>"`
+   - Do NOT prompt or show suggestions (unless `--interactive`)
+   - Just commit with the best generated message
+7. **Push** (if --push):
+   - Get remote: `git config branch.<branch>.remote` or use `--remote` or default to "origin"
+   - Get branch: Use `--branch` or `git branch --show-current`
+   - Push: `git push -o ci.skip <remote> HEAD:<branch>`
+
+## Commit Format
+
+**Format**: `<type>: <description>` (lowercase, no footers)
+
+**Types**: `chore`, `feat`, `fix`, `docs`, `refactor`, `test`, `ci`
+
+## Output
+
+**Default mode (auto-commit, no prompts):**
+
+```
+Commit: /path/to/repo
+Changed: 14 files (+588, -210)
+Type: chore
+
+Committed: chore: game-common consistency fixes (a3b2c1d)
+```
+
+**Interactive mode (`--interactive` flag):**
+
+```
+Suggestions:
+  1. docs: add implementation guide
+  2. feat: implement core logic
+Select [1-2]: 1
+
+Committed: docs: add implementation guide (a3b2c1d)
+```
+
+## Error Handling
+
+- Error if not in a git repository
+- Warning if no changes to commit (working tree clean)
+- Error if commit fails (show git error)
+- Warning if push fails (show git error, commit still succeeded)
+- Error if `--path` directory doesn't exist
+- Warning if large number of files changed (suggest splitting commit)
+
+## Examples
+
+```bash
+# Auto-commit with generated message
+/git-commit
+
+# Interactive selection
+/git-commit --interactive
+
+# Explicit message and push
+/git-commit "fix validation bug" --type fix --push
+
+# Auto-commit in specific directory
+/git-commit --path ./services
+
+# Preview what would be committed
+/git-commit --dry-run
+
+# Commit and push to specific branch
+/git-commit --branch develop --remote origin --push
+```

package/commands/insights-extract.md

@@ -0,0 +1,109 @@
+---
+description: Analyze the session for development mistakes and lessons learned
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+argument-hint: "[category] [--out-dir <dir>]"
+---
+
+# /insights-extract – Extract Development Lessons
+
+Analyzes the current session to identify general development mistakes, how they were discovered, and lessons learned. Always saves insights as individual files with frontmatter.
+
+## Usage
+
+```
+/insights-extract
+/insights-extract tool-usage
+/insights-extract validation --out-dir docs/insights
+```
+
+## Arguments
+
+- `category` (optional): Focus on a specific mistake category (e.g., `tool-usage`, `dependencies`, `validation`).
+- `--out-dir` (optional): The directory to save insight files in. Defaults to `insights/`.
+
+## Goal
+
+1.  **Analyzes** the conversation for development errors and corrections.
+2.  **Identifies** general patterns that apply beyond the current task.
+3.  **Extracts** category, topic, and applicability from the insight.
+4.  **Saves** individual insights to the output directory with frontmatter.
+
+## Output Format
+
+Creates files with this structure:
+
+```markdown
+---
+category: testing
+topic: json-response-type-safety
+applies_to:
+  - API testing
+  - Hono testing
+created: "2025-01-07"
+applied: false
+---
+
+# [Category]: [Mistake Description]
+
+- **MISTAKE**: [What went wrong]
+- **DISCOVERY**: [How the mistake was discovered]
+- **FIX**: [How to avoid this mistake]
+- **APPLIES TO**: [Types of tasks this affects]
+```
+
+## Frontmatter Fields
+
+- `category`: Primary technology/domain (e.g., `testing`, `typescript`, `hono`)
+- `topic`: Specific topic slug (e.g., `json-response-type-safety`)
+- `applies_to`: List of contexts where this applies (e.g., `["API testing", "Hono testing"]`)
+- `created`: ISO date when insight was created
+- `applied`: Boolean tracking if insight has been integrated into guidelines (always `false` on creation)
+
+The `applies_to` list is used by `/insights-integrate` to determine which guideline files this insight should be added to.
+
+## Output
+
+```
+Extracted insights from current session
+
+Insights saved:
+- insights/testing-json-response-type-safety.md
+  Category: testing | Topic: json-response-type-safety
+  Applies to: API testing, Hono testing
+
+- insights/typescript-strict-null-checks.md
+  Category: typescript | Topic: strict-null-checks
+  Applies to: Type safety, Error handling
+
+Total: 2 insights extracted
+
+Next Steps:
+1. Review extracted insight files in insights/ directory
+2. Verify content: Check that mistakes, discoveries, and fixes are accurately captured
+3. Integrate: /insights-integrate --all - Transform insights into guideline structure
+4. Alternative: /insights-integrate insights/<file>.md - Integrate specific insight
+5. Share: Discuss insights with team if applicable before integration
+```
+
+## Examples
+
+```bash
+# Extract all insights from current session
+/insights-extract
+
+# Extract insights for specific category
+/insights-extract tool-usage
+
+# Save to custom directory
+/insights-extract validation --out-dir docs/insights
+```
+
+## Error Handling
+
+- No insights found: Warning if no development mistakes or corrections are detected in session
+- Invalid category: Error if specified category does not exist or is malformed
+- File write error: Error if insight file cannot be saved to output directory

package/commands/insights-integrate.md

@@ -0,0 +1,100 @@
+---
+description: Convert insights from a category into a progressive disclosure skill
+model: sonnet
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+argument-hint: "[category] [--dry-run] [--force] [--output <path>]"
+---
+
+# /insights-integrate – Convert Insights to Skill
+
+Convert insights from a category into a Claude skill with progressive disclosure structure.
+
+## Arguments
+
+- `category` (required) - Category to convert (e.g., `hono`, `typescript`, `workflow`)
+- `--dry-run` - Preview without writing
+- `--force` - Overwrite existing skill instead of merging
+- `--output <path>` - Custom output path (default: `.claude/skills/{category}/SKILL.md`)
+
+## Workflow
+
+1. **Discover:** Search `insights/` for category files, extract Problem/Solution/Example, group by topic
+2. **Generate Structure:**
+   - Metadata: `{category}-best-practices`, description under 150 chars starting with "Use when..."
+   - SKILL.md: Requirements (optional), Essentials (3-7 items), Examples (code), Progressive disclosure (detail refs)
+   - Detail files: Guideline, Rationale, How to Apply, Example (bad vs good), Related
+3. **Merge:** If skill exists and not `--force`: combine metadata, deduplicate Essentials (keep 3-7), append examples, add detail file refs
+4. **Output:** `--dry-run` shows structure without writing, otherwise creates directory and files
+
+## Structure Template
+
+**SKILL.md:**
+
+````markdown
+---
+name: {category}-best-practices
+description: Use when working with {category} to {purpose}. Apply for {scenarios}.
+---
+
+## Essentials
+
+- {Core guideline 1}
+- {Core guideline 2-6}
+
+## Examples
+
+```typescript
+{Code showing best practice}
+```
+````
+
+## Progressive disclosure
+
+- **details/{topic}.md** - When {scenario}
+
+````
+
+**Detail file (details/{topic}.md):**
+```markdown
+# {topic}: {Title}
+
+**Guideline:** {Rule statement}
+**Rationale:** {Why this matters}
+
+**How to Apply:**
+1. {Step-by-step}
+
+**Example:**
+```typescript
+// Bad
+{Anti-pattern}
+// Good
+{Correct usage}
+````
+
+**Related:** details/{other-topic}.md
+
+```
+
+## Example Output
+
+```
+
+[OK] Skill created: .claude/skills/api/SKILL.md
+
+- 12 insights converted, 4 topics
+- Created details/status-codes.md, details/validation-safety.md
+
+```
+
+## Error Handling
+
+- Missing category: ask user
+- No insights found: suggest `/insights-extract [category]`
+- Output not writable: report error
+```