@plaited/development-skills 0.5.0 → 0.6.1

package/.claude/commands/lsp-hover.md

@@ -1,57 +0,0 @@
----
-description: Get TypeScript type signature + TSDoc documentation at a position
-allowed-tools: Bash
----
-
-# LSP Hover
-
-Get type signature and TSDoc documentation at a specific position in a TypeScript/JavaScript file.
-
-**Arguments:** $ARGUMENTS
-
-## When to Use Each Tool
-
-| Tool | Purpose |
-|------|---------|
-| **Glob** | Find files by pattern |
-| **Grep** | Search text content |
-| **lsp-find** | Search TypeScript symbols |
-| **lsp-hover** | Get type info + TSDoc documentation |
-
-## Usage
-
-```
-/lsp-hover <file> <line> <char>
-```
-
-- `file`: Path to TypeScript/JavaScript file (absolute, relative, or package export path)
-- `line`: Line number (0-indexed)
-- `char`: Character position (0-indexed)
-
-## Instructions
-
-### Step 1: Parse Arguments
-
-Extract file path, line, and character from `$ARGUMENTS`.
-
-If arguments are missing, show usage:
-```
-Usage: /lsp-hover <file> <line> <char>
-
-Example: /lsp-hover src/utils/parser.ts 42 15
-```
-
-### Step 2: Run LSP Hover
-
-Execute the development-skills CLI command:
-```bash
-bunx @plaited/development-skills lsp-hover <file> <line> <char>
-```
-
-### Step 3: Format Output
-
-Parse the JSON output and present the type information in a readable format:
-
-- Show the type signature in a code block
-- If documentation is present, show it below
-- If no hover info found, explain that no type information is available at that position

package/.claude/commands/lsp-refs.md

@@ -1,64 +0,0 @@
----
-description: Find all references to a TypeScript symbol across the codebase
-allowed-tools: Bash
----
-
-# LSP References
-
-Find all references to a symbol at a specific position. Use this before modifying or deleting exports to understand impact.
-
-**Arguments:** $ARGUMENTS
-
-## When to Use Each Tool
-
-| Tool | Purpose |
-|------|---------|
-| **Glob** | Find files by pattern |
-| **Grep** | Search text content |
-| **lsp-find** | Search TypeScript symbols |
-| **lsp-refs** | Find all references to a symbol |
-
-## Usage
-
-```
-/lsp-refs <file> <line> <char>
-```
-
-- `file`: Path to TypeScript/JavaScript file
-- `line`: Line number (0-indexed)
-- `char`: Character position (0-indexed)
-
-## Instructions
-
-### Step 1: Parse Arguments
-
-Extract file path, line, and character from `$ARGUMENTS`.
-
-If arguments are missing, show usage:
-```
-Usage: /lsp-refs <file> <line> <char>
-
-Example: /lsp-refs src/utils/parser.ts 42 10
-```
-
-### Step 2: Run LSP References
-
-Execute the development-skills CLI command:
-```bash
-bunx @plaited/development-skills lsp-refs <file> <line> <char>
-```
-
-### Step 3: Format Output
-
-Parse the JSON output and present references grouped by file:
-
-**Found X references:**
-
-`src/file1.ts`
-- Line 42: `const x = targetSymbol()`
-- Line 58: `import { targetSymbol } from...`
-
-`src/file2.ts`
-- Line 15: `targetSymbol.method()`
-
-If no references found, indicate that the symbol may be unused or only defined.

package/.claude/commands/scaffold-rules.md

@@ -1,221 +0,0 @@
----
-description: Scaffold or merge development rules for your AI coding agent
-allowed-tools: Glob, Read, Write, Edit, AskUserQuestion
----
-
-# Scaffold Rules
-
-Generate development rules adapted to the user's AI coding agent environment.
-
-**Arguments:** $ARGUMENTS (optional: rule categories to scaffold)
-
-## Instructions
-
-### Step 1: Get Processed Templates from CLI
-
-Call the CLI to get rule templates with variables already processed:
-
-```bash
-bunx @plaited/development-skills scaffold-rules --format=json
-```
-
-The CLI will:
-- Read bundled rule templates from the package
-- Process template variables ({{LINK:*}}, {{#if}}, etc.)
-- Output JSON with processed content
-
-Parse the JSON output to get available templates. The output structure is:
-```json
-{
-  "templates": {
-    "accuracy": {
-      "filename": "accuracy.md",
-      "content": "# Accuracy and Confidence Standards\n...",
-      "description": "95% confidence threshold, verification protocols"
-    },
-    "testing": { ... },
-    ...
-  }
-}
-```
-
-### Step 2: Detect Agent & Scan Existing Rules
-
-The CLI supports 2 target formats:
-
-| Target | Rules Location | Use Case |
-|--------|----------------|----------|
-| `claude` | `.claude/rules/` | Claude Code (default) |
-| `agents-md` | `.plaited/rules/` + `AGENTS.md` | Universal format for Cursor, Factory, Copilot, Windsurf, Cline, Aider, and 60,000+ other projects |
-
-Check for existing configuration:
-```
-.claude/          → Use --agent=claude (default)
-AGENTS.md         → Use --agent=agents-md
-.plaited/rules/   → Use --agent=agents-md
-Any other agent   → Use --agent=agents-md (universal)
-```
-
-**Always scan for existing rules before writing.** Use Read tool to check what's already there.
-
-Analyze existing content to understand:
-- What conventions are already defined
-- What sections/topics are covered
-- The writing style and format used
-
-### Step 3: Ask User Preferences
-
-Present available templates from CLI output and ask which to scaffold (if not provided in $ARGUMENTS):
-
-```
-? Select rule categories to scaffold:
-  ◉ accuracy - 95% confidence threshold, verification protocols
-  ◉ bun-apis - Prefer Bun over Node.js APIs
-  ◉ git-workflow - Conventional commits, multi-line messages
-  ◉ github - GitHub CLI patterns for PRs/issues
-  ◉ code-review - TypeScript conventions, module organization
-  ◉ testing - Bun test runner conventions
-```
-
-### Step 4: Propose Merges (If Existing Rules Found)
-
-If existing rules were found in Step 2, compare with CLI output:
-
-1. **Identify overlaps**: Which templates already exist as files
-2. **Show what would be added**: Preview the content from CLI
-3. **Ask for approval**:
-
-```
-? Existing rules found. How would you like to proceed?
-
-  For "git-workflow.md" (exists):
-  ◯ Keep existing (skip)
-  ◉ Merge (add missing sections)
-  ◯ Replace entirely
-
-  For "testing.md" (new):
-  ◉ Add to rules
-  ◯ Skip
-```
-
-For merges:
-- Use Read to get existing content
-- Show diff of what would change
-- Get approval before writing
-
-### Step 5: Write Rules
-
-After user approval, write the rules using the content from CLI output:
-
-- Use Write tool with `content` from CLI JSON
-- Create directories if needed (`.claude/rules/` or `.plaited/rules/`)
-- Write/merge files as approved
-- Report what was created/modified
-
-### Rule Content Guidelines
-
-The CLI processes template variables automatically. The content in the JSON output is ready to write to files.
-
-**Template Processing:**
-The CLI handles:
-- Template variable substitution ({{LINK:*}}, {{AGENT_NAME}}, etc.)
-- Capability-based conditionals ({{#if has-sandbox}}, {{#if supports-slash-commands}})
-- Template header removal
-- Cross-reference formatting for detected agent
-
-**Available Rule Topics:**
-
-**Bun APIs:**
-- Prefer `Bun.file()` over `fs` APIs
-- Use `Bun.$` for shell commands
-- Use `Bun.write()` for file writes
-- Use `import.meta.dir` for current directory
-
-**Git Workflow:**
-- Conventional commit prefixes (feat, fix, refactor, docs, chore, test)
-- Multi-line commit message format
-- Sandbox workarounds (Claude Code only)
-
-**GitHub CLI:**
-- Prefer `gh` CLI over WebFetch for GitHub URLs
-- PR review patterns
-- Issue/PR JSON field references
-
-**TypeScript Conventions:**
-- Prefer `type` over `interface`
-- No `any` types (use `unknown` with guards)
-- Arrow functions preferred
-- Object parameter pattern for 2+ params
-- PascalCase for types, `PascalCaseSchema` for Zod schemas
-
-**Testing Patterns:**
-- Use `test()` instead of `it()`
-- `*.spec.ts` naming convention
-- No conditionals around assertions
-- Assert existence before checking values
-
-### Step 6: Output Summary
-
-After completion, summarize what was done:
-
-```
-✅ Rules scaffolded for Claude Code:
-
-  Created:
-    • .claude/rules/testing.md - Bun test conventions
-    • .claude/rules/bun-apis.md - Prefer Bun over Node.js
-
-  Merged:
-    • .claude/rules/git-workflow.md - Added commit message formats
-
-  Skipped:
-    • accuracy.md - Already exists, user chose to keep
-
-💡 Review the generated rules at .claude/rules/ and customize as needed.
-```
-
-### CLI Usage
-
-The scaffold-rules CLI supports 2 target formats:
-
-```bash
-# Default: outputs all rules for Claude Code
-bunx @plaited/development-skills scaffold-rules
-
-# Universal AGENTS.md format (works with Cursor, Factory, Copilot, Windsurf, Cline, Aider, etc.)
-bunx @plaited/development-skills scaffold-rules --agent=agents-md
-
-# Custom paths (for specific agent directories or monorepos)
-bunx @plaited/development-skills scaffold-rules --agent=agents-md --rules-dir=.cursor/rules
-bunx @plaited/development-skills scaffold-rules --agent=agents-md --agents-md-path=docs/AGENTS.md
-
-# Filter specific rules
-bunx @plaited/development-skills scaffold-rules --rules testing --rules bun-apis
-```
-
-**Options:**
-- `--agent` / `-a`: Target format (`claude` or `agents-md`)
-- `--rules-dir` / `-d`: Custom rules directory path (overrides default)
-- `--agents-md-path` / `-m`: Custom AGENTS.md file path (default: `AGENTS.md`)
-- `--format` / `-f`: Output format (json)
-- `--rules` / `-r`: Specific rules to include (can be used multiple times)
-
-**Output Structure:**
-The JSON output includes metadata about the target:
-```json
-{
-  "agent": "agents-md",
-  "rulesPath": ".plaited/rules",
-  "agentsMdPath": "AGENTS.md",
-  "format": "agents-md",
-  "supportsAgentsMd": true,
-  "agentsMdContent": "# AGENTS.md\n...",
-  "templates": { ... }
-}
-```
-
-For `agents-md` format, write:
-1. Individual rule files to the path specified in `rulesPath`
-2. The `agentsMdContent` to the path specified in `agentsMdPath`
-
-This provides maximum portability - rules work with any AGENTS.md-compatible agent (60,000+ projects support this format).

package/.claude/commands/validate-skill.md

@@ -1,29 +0,0 @@
----
-description: Validate skill directories against AgentSkills spec
-allowed-tools: Bash, mcp__agent-skills-spec__*
----
-
-# Validate Skills
-
-Validate skill directories against the AgentSkills specification.
-
-**Paths to validate:** $ARGUMENTS (default: `.claude/skills/`)
-
-## Instructions
-
-### Step 1: Run Validation
-
-Execute the development-skills CLI command:
-```bash
-bunx @plaited/development-skills validate-skill $ARGUMENTS
-```
-
-If no arguments provided, defaults to `.claude/skills/`.
-
-### Step 2: Report Results
-
-Show the CLI output to the user. If there are errors, use the `agent-skills-spec` MCP server to get the latest specification and explain how to fix them.
-
-### Step 3: Query Spec (if needed)
-
-For clarification on validation rules, query the `agent-skills-spec` MCP server for the current specification.

package/.claude/rules/git-workflow.md

@@ -1,66 +0,0 @@
-<!--
-RULE TEMPLATE - Distributed via /scaffold-rules
-Variables: {{#if has-sandbox}}, {{#if supports-slash-commands}}
--->
-
-# Git Workflow
-
-## Commit Message Format
-
-{{#if has-sandbox}}
-When creating commits with multi-line messages, use single-quoted strings instead of heredocs. The sandbox environment restricts temp file creation needed for heredocs.
-{{/if}}
-{{^if has-sandbox}}
-Use multi-line commit messages for detailed changes:
-{{/if}}
-
-{{#if has-sandbox}}
-```bash
-# ✅ CORRECT: Single-quoted multi-line string
-git commit -m 'refactor: description here
-
-Additional context on second line.
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>'
-
-# ❌ WRONG: Heredoc syntax (fails in sandbox)
-git commit -m "$(cat <<'EOF'
-refactor: description here
-EOF
-)"
-```
-
-The heredoc approach fails with:
-```
-(eval):1: can't create temp file for here document: operation not permitted
-```
-{{/if}}
-{{^if has-sandbox}}
-```bash
-git commit -m "refactor: description here
-
-Additional context on second line."
-```
-{{/if}}
-
-## Pre-commit Hooks
-
-**Never use `--no-verify`** to bypass pre-commit hooks. If hooks fail, it indicates a real issue that must be fixed:
-
-1. Investigate the error message
-2. Fix the underlying issue (lint errors, format issues, test failures)
-3. Re-run the commit
-
-Using `--no-verify` masks problems and defeats the purpose of automated quality checks.
-
-## Commit Conventions
-
-Follow conventional commits format:
-- `feat:` - New features
-- `fix:` - Bug fixes
-- `refactor:` - Code changes that neither fix bugs nor add features
-- `docs:` - Documentation only changes
-- `chore:` - Maintenance tasks
-- `test:` - Adding or updating tests

package/.claude/skills/code-documentation/SKILL.md

@@ -1,47 +0,0 @@
----
-name: code-documentation
-description: TSDoc standards for TypeScript/JavaScript code. Automatically invoked when writing, reviewing, or editing any TSDoc comments, code documentation, or API documentation. (project)
-license: ISC
-compatibility: Requires bun
----
-
-# Code Documentation Skill
-
-## Purpose
-
-This skill provides TSDoc format templates, type documentation guidelines, and maintenance workflows. Use this when:
-- Writing or editing TSDoc comments for any function, type, or module
-- Reviewing documentation quality
-- Creating comprehensive API documentation
-- Documenting complex type structures
-- Cleaning up non-compliant comments (performance notes, timestamps, inline explanations)
-- Synchronizing out-of-sync TSDoc with code changes
-- Removing orphaned documentation for deleted code
-
-**Key Standard**: No `@example` sections - tests and stories serve as living examples.
-
-## Quick Reference
-
-- **Creating TSDoc**: See [workflow.md](references/workflow.md) for the generation workflow
-- **Maintaining TSDoc**: See [maintenance.md](references/maintenance.md) for cleanup and sync guidelines
-
-This skill contains detailed templates for:
-- Public API Functions
-- Internal Module Documentation
-- Public and Internal Types
-- Helper Functions
-- Behavioral Programming Functions
-- Special Annotations (Security, Performance, Deprecated)
-- Type Documentation (Complex Objects, Unions, Functions, Utilities, Branded Types, etc.)
-
-## Navigation
-
-- [workflow.md](references/workflow.md) - TSDoc generation workflow (4 phases)
-- [maintenance.md](references/maintenance.md) - Comment policy, sync tasks, orphaned doc handling
-- [public-api-templates.md](references/public-api-templates.md) - Templates for public-facing APIs
-- [internal-templates.md](references/internal-templates.md) - Templates for internal code and modules
-- [type-documentation.md](references/type-documentation.md) - Comprehensive type documentation templates
-
-## Related Skills
-
-- **typescript-lsp**: Use for type verification and discovery during documentation workflow. Essential for Phase 1 (type analysis) and Phase 2 (usage discovery) of the TSDoc generation process. Run `lsp-hover` to verify signatures, `lsp-references` to find usages, and `lsp-symbols` to understand file structure.

package/.claude/skills/code-documentation/references/internal-templates.md

@@ -1,113 +0,0 @@
-# Internal Templates
-
-## Internal Module Documentation
-
-```typescript
-/**
- * @internal
- * @module module-name
- *
- * Purpose: Why this module exists in the codebase
- * Architecture: How it fits into the overall system design
- * Dependencies: What this module depends on (be specific)
- * Consumers: What parts of the system use this module
- *
- * Maintainer Notes:
- * - Key implementation details and design decisions
- * - Important invariants that must be maintained
- * - Tricky aspects of the implementation
- * - Performance-critical sections with complexity analysis
- *
- * Common modification scenarios:
- * - When you might need to modify this module
- * - How to extend functionality safely
- * - What to watch out for when making changes
- *
- * Performance considerations:
- * - Optimization strategies used
- * - Memory management concerns
- * - Computational complexity (Big-O notation)
- *
- * Known limitations:
- * - Current constraints or technical debt
- * - Planned improvements
- * - Workarounds for known issues
- */
-```
-
-## Internal Types
-
-```typescript
-/**
- * @internal
- * What this type represents internally and why it exists.
- * How it's used in the implementation.
- *
- * @property propName - Internal property purpose
- *
- * @remarks
- * - Implementation-specific constraints
- * - Why this structure was chosen
- */
-type InternalType = {
-  // Implementation-specific properties
-}
-```
-
-## Internal Helper Functions
-
-```typescript
-/**
- * @internal
- * Brief description of what this internal function does.
- * Why it exists and how it's used within the module.
- *
- * @param paramName - Parameter purpose
- * @returns Return value meaning
- *
- * @remarks
- * - Algorithm details (e.g., "Fisher-Yates shuffle")
- * - Complexity: O(n) where n is...
- * - Why this approach was chosen
- */
-const internalHelper = () => { ... }
-```
-
-## Security-Sensitive Code
-
-```typescript
-/**
- * @internal
- * SECURITY: This function handles [sensitive operation].
- *
- * Security considerations:
- * - Input sanitization approach
- * - XSS/injection prevention measures
- * - Authentication/authorization requirements
- */
-```
-
-## Performance-Critical Code
-
-```typescript
-/**
- * @internal
- * PERFORMANCE: Hot path - called [frequency/context].
- *
- * Performance notes:
- * - Optimization strategy (e.g., "minimal allocations")
- * - Caching approach (e.g., "WeakMap cache")
- * - Complexity: O(1) lookup after initial computation
- */
-```
-
-## Required Elements for Internal Modules
-
-### All Internal Modules Must Include
-
-- Purpose and architecture context
-- Dependencies and consumers
-- Maintainer notes
-- Modification scenarios
-- Performance considerations
-- Known limitations