@plaited/development-skills 0.5.0 → 0.6.0

package/.claude/skills/code-documentation/references/public-api-templates.md

@@ -1,100 +0,0 @@
-# Public API Templates
-
-## Public API Functions
-
-```typescript
-/**
- * Concise one-line description of functionality.
- * Extended explanation providing context, use cases, and when to use this.
- *
- * @template T - Description of generic type parameter and constraints
- * @param paramName - Parameter purpose, constraints, and expected values
- * @returns Description of return value, what it represents, and guarantees
- *
- * @remarks
- * - Key behavioral characteristics
- * - Important execution details
- * - Performance considerations (with Big-O if relevant)
- * - Common pitfalls or gotchas
- * - Threading/async behavior if applicable
- *
- * @throws {ErrorType} When and why this error occurs
- *
- * @see {@link RelatedFunction} for related functionality
- * @see {@link RelatedType} for type details
- * @since 1.0.0
- */
-```
-
-## Public Types
-
-```typescript
-/**
- * Description of what this type represents in the API.
- * When and why to use this type.
- *
- * @template T - Generic parameter description and constraints
- * @property propName - What this property controls or represents
- * @property optionalProp - Purpose and when to include this property
- *
- * @remarks
- * - Type constraints and relationships
- * - Common usage patterns
- * - Integration with other types
- *
- * @see {@link RelatedType} for related type definitions
- * @since 1.0.0
- */
-export type TypeName<T> = {
-  propName: string;
-  optionalProp?: number;
-}
-```
-
-## Behavioral Programming Functions
-
-**CRITICAL:** For behavioral programming APIs (bSync, bThread, behavioral, useBehavioral), always use factory functions in documentation - never raw `yield` statements.
-
-```typescript
-/**
- * Creates a behavioral thread for coordinating async operations.
- * Explain the coordination pattern and synchronization approach.
- *
- * @param config - Thread configuration options
- * @returns Configured behavioral thread
- *
- * @remarks
- * - Thread execution model (sequential through sync points)
- * - Event coordination semantics
- * - Blocking precedence rules
- * - Repetition behavior
- * - Integration with trigger/feedback mechanisms
- *
- * @see {@link bSync} for creating sync points
- * @see {@link behavioral} for program setup
- * @see {@link Idioms} for synchronization options
- * @since 1.0.0
- */
-```
-
-## Deprecated Code
-
-```typescript
-/**
- * @deprecated Use {@link NewFunction} instead. Will be removed in v8.0.
- *
- * Migration path: [Brief guidance on how to migrate]
- *
- * @see {@link NewFunction}
- */
-```
-
-## Required Elements by Context
-
-### All Public APIs Must Include
-
-- One-line description + extended context
-- `@param` for all parameters
-- `@returns` for return values
-- `@remarks` section with behavioral notes
-- `@see` tags to related APIs

package/.claude/skills/code-documentation/references/type-documentation.md

@@ -1,116 +0,0 @@
-# Type Documentation Guidelines
-
-**IMPORTANT**: This project prefers `type` over `interface` in both code and TSDoc comments. Always use `type` declarations unless there's a specific need for interface features like declaration merging.
-
-## Type Analysis Process
-
-When documenting types, use the **typescript-lsp** skill for accurate type discovery:
-
-1. **Analyze type structure** using typescript-lsp:
-   - Run `lsp-symbols` to list all type definitions in a file
-   - Run `lsp-hover` on the type to get the full signature
-   - Identify all properties and their types
-   - Find optional vs required properties
-   - Trace generic type parameters
-   - Identify union and intersection types
-
-2. **Find type relationships** using typescript-lsp:
-   - Run `lsp-references` to find all usages of the type
-   - Run `lsp-find` to search for related types by name pattern
-   - What types does this extend or implement?
-   - What types reference this type?
-   - What utility types are derived from this?
-   - Are there branded/nominal types involved?
-
-3. **Discover usage patterns:**
-   - How is this type constructed?
-   - What validation occurs?
-   - Are there Zod schemas associated?
-   - What are the common configurations?
-
-4. **Document from analysis:**
-   - Property purposes from usage context
-   - Constraints from validation/tests
-   - Relationships from type dependencies
-   - Patterns from real usage in framework code, stories, and test files
-
-## Type Documentation Requirements
-
-All TypeScript type patterns (complex objects, unions, functions, mapped types, recursive types, etc.) should follow standard TSDoc format with these conventions:
-
-### Core Requirements
-
-- **Always use `type` over `interface`** (unless extending a single interface for branding)
-- **Include `@property`** for all properties with: purpose, constraints, and when to use
-- **Document `@template`** parameters with: constraint, purpose, and where it flows
-- **Add `@remarks`** for: validation rules, constraints, common patterns, performance notes
-- **Cross-reference** related types, factory functions, type guards, and Zod schemas using `@see`
-- **Mark internal types** with `@internal` for non-public APIs
-
-### Zod Schema Integration
-
-When types have associated Zod schemas, document validation in `@remarks`:
-
-```typescript
-/**
- * @remarks
- * Validation:
- * - Schema: {@link ConfigSchema}
- * - Required fields: [list]
- * - Optional fields: [list]
- * - Default values: [from schema defaults]
- */
-```
-
-## Property Documentation
-
-**Required for each property:**
-```typescript
-@property propName - [Purpose] [Constraints] [When to use]
-```
-
-**Discovery sources:**
-1. From usage: How the property is accessed/used
-2. From tests: What values are tested, edge cases
-3. From validation: Zod schemas, type guards
-4. From defaults: Default values in code
-
-## Generic Type Parameters
-
-**Always document with:**
-```typescript
-@template T - [Constraint] [Purpose] [Where it flows]
-```
-
-**Discovery process:**
-1. Find where T is used in type body
-2. Identify constraints (extends clauses)
-3. Trace how T flows through type
-4. Note variance (in/out if relevant)
-
-## Cross-Referencing Types
-
-**Always link:**
-- Related types (subtypes, supertypes)
-- Factory functions that create instances
-- Type guards that check instances
-- Validation schemas
-- Consumer functions/classes
-
-**Format:**
-```typescript
-/**
- * @see {@link ParentType} for base type definition
- * @see {@link createInstance} for creating valid instances
- * @see {@link isInstanceOf} for runtime type checking
- * @see {@link InstanceSchema} for validation schema
- * @see {@link Consumer} for primary consumer
- */
-```
-
-## Required Elements for All Types
-
-- Description of what it represents
-- `@property` documentation for all properties
-- `@template` for generic parameters
-- `@remarks` for constraints and patterns

package/.claude/skills/code-documentation/references/workflow.md

@@ -1,60 +0,0 @@
-# TSDoc Generation Workflow
-
-When creating or updating TSDoc comments, follow this systematic exploration process.
-
-**Prerequisite**: Use the **typescript-lsp** skill for type verification throughout this workflow. The LSP tools provide accurate type information directly from the TypeScript compiler.
-
-## Phase 1: Type & Interface Analysis
-
-1. **Identify the target** (function, type, class, or module)
-2. **Analyze type signatures** using typescript-lsp:
-   - Run `lsp-symbols` to get file structure overview
-   - Run `lsp-hover` on the target to get exact type signatures
-   - Parameter types and constraints
-   - Return types
-   - Generic type parameters
-   - Type relationships and dependencies
-3. **Trace type dependencies:**
-   - Run `lsp-references` to find what depends on this type
-   - What types does this depend on?
-   - What types depend on this?
-   - Are there related utility types?
-
-## Phase 2: Usage Reference Discovery
-
-1. **Find all usage locations** using typescript-lsp:
-   - Run `lsp-references` on the target symbol
-   - Run `lsp-find` to search for related patterns
-   - Identify calling patterns
-   - Note common usage contexts
-2. **Analyze integration points:**
-   - How is this used in the architecture?
-   - What modules consume this?
-   - What are the typical call chains?
-
-## Phase 3: Test & Story Analysis
-
-1. **Review test files** (`.test.ts`, `.spec.ts`):
-   - What behaviors are tested?
-   - What edge cases are covered?
-   - What scenarios are validated?
-2. **Review story files** (`.stories.tsx`):
-   - How is this used in practice?
-   - What real-world scenarios exist?
-   - What configurations are demonstrated?
-
-## Phase 4: Documentation Generation
-
-1. **Synthesize findings** from phases 1-3
-2. **Apply appropriate TSDoc template** from this skill
-3. **Cross-reference related APIs** using `@see` tags
-4. **Document discovered constraints** in `@remarks`
-5. **Note performance characteristics** if evident from usage
-6. **Identify limitations** found in tests or usage patterns
-
-## Templates
-
-After completing the workflow phases, apply the appropriate template:
-- @public-api-templates.md - Public-facing APIs
-- @internal-templates.md - Internal code and modules
-- @type-documentation.md - Type documentation

package/.claude/skills/scaffold-rules/SKILL.md

@@ -1,104 +0,0 @@
----
-name: scaffold-rules
-description: Scaffold development rules for AI coding agents. Auto-invoked when user asks about setting up rules, coding conventions, or configuring their AI agent environment.
-license: ISC
-compatibility: Requires bun
-allowed-tools: Glob, Read, Write, Edit, AskUserQuestion
----
-
-# Scaffold Rules
-
-Scaffold and merge development rules adapted to different AI coding agent environments.
-
-## Purpose
-
-Use this skill when the user wants to:
-- Set up development rules or coding conventions
-- Configure their AI coding agent (Claude Code, Cursor, Copilot, etc.)
-- Add or update project guidelines
-- Standardize conventions across a team
-
-## Supported Agents
-
-| Agent | Config Location | Format |
-|-------|-----------------|--------|
-| Claude Code | `.claude/rules/*.md` | Separate markdown files |
-| Cursor | `.cursorrules` or `.cursor/rules/*.md` | Single or multi-file |
-| GitHub Copilot | `.github/copilot-instructions.md` | Single file |
-| Windsurf | `.windsurfrules` | Single file |
-| Cline/Roo | `.clinerules` | Single file |
-| Aider | `.aider.conf.yml` | YAML config |
-
-## Rule Categories
-
-### Bun APIs
-Prefer Bun's native APIs over Node.js equivalents:
-- `Bun.file()` over `fs` APIs
-- `Bun.$` for shell commands
-- `Bun.write()` for file writes
-- `import.meta.dir` for current directory
-
-### Git Workflow
-Commit conventions and version control:
-- Conventional commit prefixes: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `test:`
-- Multi-line commit message formatting
-- Agent-specific sandbox workarounds
-
-### GitHub CLI
-Prefer `gh` CLI for GitHub operations:
-- PR review and creation patterns
-- Issue management
-- JSON output field references
-- Authentication benefits over WebFetch
-
-### TypeScript Conventions
-Code style standards:
-- Prefer `type` over `interface`
-- No `any` types (use `unknown` with type guards)
-- Arrow functions preferred
-- Object parameter pattern for 2+ parameters
-- PascalCase for types, `PascalCaseSchema` suffix for Zod schemas
-
-### Testing Patterns
-Bun test runner conventions:
-- Use `test()` instead of `it()`
-- `*.spec.ts` file naming
-- No conditionals around assertions
-- Assert existence before checking values
-
-### Module Organization
-Import/export patterns for Bun/TypeScript projects:
-- No `index.ts` files—use named re-export files matching folder names
-- Single feature packages expose the feature file directly as main
-- Explicit `.ts` extensions in all imports
-- Flat re-export structure: `src/acp.ts` re-exports from `src/acp/`
-
-## Merge Behavior
-
-**Always scans existing rules first.** When existing rules are found:
-
-1. **Analyze overlap** - Identify sections covering same topics
-2. **Propose merge** - Show what would be added/changed
-3. **User approval** - Ask before modifying:
-   - Keep existing (skip new content)
-   - Merge (add missing sections)
-   - Replace entirely
-
-This ensures the command never overwrites user customizations without consent.
-
-## Agent Adaptations
-
-Content is adapted based on agent capabilities:
-
-- **Sandbox awareness**: Include/exclude sandbox workarounds based on agent
-- **Tool references**: Adjust tool names (e.g., "Bash tool" → "terminal")
-- **Format**: Single file vs multi-file based on agent convention
-- **Length**: Condense for agents with size limits
-
-## Usage
-
-Run the `/scaffold-rules` command to interactively scaffold rules, or invoke when user asks about:
-- "Set up coding conventions"
-- "Configure my AI agent"
-- "Add development rules"
-- "What rules should I have?"

package/.claude/skills/typescript-lsp/SKILL.md

@@ -1,249 +0,0 @@
----
-name: typescript-lsp
-description: Search TypeScript SYMBOLS (functions, types, classes) - NOT text. Use Glob to find files, Grep for text search, LSP for symbol search. Provides type-aware results that understand imports, exports, and relationships.
-license: ISC
-compatibility: Requires bun
-allowed-tools: Bash
-metadata:
-  file-triggers: "*.ts,*.tsx,*.js,*.jsx"
----
-
-# TypeScript LSP Skill
-
-## Purpose
-
-This skill provides TypeScript Language Server Protocol integration for **exploring and understanding** TypeScript/JavaScript codebases. 
-
-**IMPORTANT**: Prefer LSP tools over Grep/Glob when working with `*.ts`, `*.tsx`, `*.js`, `*.jsx` files. LSP provides type-aware results that understand imports, exports, and symbol relationships.
-
-Use these tools to:
-- **Explore codebases** - Find symbols, understand module structure, discover implementations
-- **Find references** - Type-aware search across the entire codebase (better than grep for symbols)
-- **Understand types** - Get full type signatures, generics, and documentation
-- **Verify before editing** - Check all usages before modifying or deleting exports
-- **Navigate code** - Jump to definitions, find implementations
-
-## 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 |
-| **lsp-refs** | Find all references to a symbol |
-| **lsp-analyze** | Batch analysis of file structure |
-
-### LSP vs Grep/Glob
-
-| Task | Use LSP | Use Grep/Glob |
-|------|---------|---------------|
-| Find all usages of a function/type | ✅ `lsp-refs` | ❌ Misses re-exports, aliases |
-| Search for a symbol by name | ✅ `lsp-find` | ❌ Matches strings, comments |
-| Get type signature + TSDoc | ✅ `lsp-hover` | ❌ Not possible |
-| Understand file exports | ✅ `lsp-analyze --exports` | ❌ Doesn't resolve re-exports |
-| Find files by pattern | ❌ | ✅ `Glob` |
-| Search non-TS files (md, json) | ❌ | ✅ `Grep` |
-| Search for text in comments/strings | ❌ | ✅ `Grep` |
-
-## When to Use
-
-**Exploring code (prefer LSP):**
-- Run `lsp-find` to search for symbols across the workspace
-- Run `lsp-symbols` to get an overview of file structure
-- Run `lsp-analyze --exports` to see what a module provides
-
-**Before editing code:**
-- Run `lsp-references` to find all usages of a symbol you plan to modify
-- Run `lsp-hover` to verify current type signatures
-
-**Before writing code:**
-- Run `lsp-find` to search for similar patterns or related symbols
-- Run `lsp-hover` on APIs you plan to use
-
-## Path Resolution
-
-All scripts accept three types of file paths:
-- **Absolute paths**: `/Users/name/project/src/file.ts`
-- **Relative paths**: `./src/file.ts` or `../other/file.ts`
-- **Package export paths**: `my-package/src/module.ts` (resolved via `Bun.resolve()`)
-
-Package export paths are recommended for portability and consistency with the package's exports field.
-
-## Scripts
-
-### Individual Scripts
-
-#### lsp-hover
-Get type information at a specific position.
-
-```bash
-bunx @plaited/development-skills lsp-hover <file> <line> <char>
-```
-
-**Arguments:**
-- `file`: Path to TypeScript/JavaScript file
-- `line`: Line number (0-indexed)
-- `char`: Character position (0-indexed)
-
-**Example:**
-```bash
-bunx @plaited/development-skills lsp-hover src/utils/parser.ts 42 10
-```
-
-#### lsp-symbols
-List all symbols in a file.
-
-```bash
-bunx @plaited/development-skills lsp-symbols <file>
-```
-
-**Example:**
-```bash
-bunx @plaited/development-skills lsp-symbols src/utils/parser.ts
-```
-
-#### lsp-references
-Find all references to a symbol.
-
-```bash
-bunx @plaited/development-skills lsp-refs <file> <line> <char>
-```
-
-**Example:**
-```bash
-bunx @plaited/development-skills lsp-refs src/utils/parser.ts 42 10
-```
-
-#### lsp-find
-Search for symbols across the workspace.
-
-```bash
-bunx @plaited/development-skills lsp-find <query> [context-file]
-```
-
-**Arguments:**
-- `query`: Symbol name or partial name
-- `context-file`: Optional file to open for project context
-
-**Example:**
-```bash
-bunx @plaited/development-skills lsp-find parseConfig
-bunx @plaited/development-skills lsp-find validateInput src/lib/validator.ts
-```
-
-### Batch Script
-
-#### lsp-analyze
-Perform multiple analyses in a single session for efficiency.
-
-```bash
-bunx @plaited/development-skills lsp-analyze <file> [options]
-```
-
-**Options:**
-- `--symbols, -s`: List all symbols
-- `--exports, -e`: List only exported symbols
-- `--hover <line:char>`: Get type info (repeatable)
-- `--refs <line:char>`: Find references (repeatable)
-- `--all`: Run symbols + exports analysis
-
-**Examples:**
-```bash
-# Get file overview
-bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --all
-
-# Check multiple positions
-bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --hover 50:10 --hover 75:5
-
-# Before refactoring: find all references
-bunx @plaited/development-skills lsp-analyze src/utils/parser.ts --refs 42:10
-```
-
-## Common Workflows
-
-### Understanding a File
-
-```bash
-# 1. Get exports overview
-bunx @plaited/development-skills lsp-analyze path/to/file.ts --exports
-
-# 2. For specific type info, hover on interesting symbols
-bunx @plaited/development-skills lsp-hover path/to/file.ts <line> <char>
-```
-
-### Before Modifying an Export
-
-```bash
-# 1. Find all references first
-bunx @plaited/development-skills lsp-refs path/to/file.ts <line> <char>
-
-# 2. Check what depends on it
-# Review the output to understand impact
-```
-
-### Finding Patterns
-
-```bash
-# Search for similar implementations
-bunx @plaited/development-skills lsp-find handleRequest
-bunx @plaited/development-skills lsp-find parseConfig
-```
-
-### Pre-Implementation Verification
-
-```bash
-# Before writing code that uses an API, verify its signature
-bunx @plaited/development-skills lsp-hover path/to/api.ts <line> <char>
-```
-
-## Output Format
-
-All scripts output JSON to stdout. Errors go to stderr.
-
-**Hover output:**
-```json
-{
-  "contents": {
-    "kind": "markdown",
-    "value": "```typescript\nconst parseConfig: (options: Options) => Config\n```"
-  },
-  "range": { "start": {...}, "end": {...} }
-}
-```
-
-**Symbols output:**
-```json
-[
-  {
-    "name": "symbolName",
-    "kind": 13,
-    "range": { "start": {...}, "end": {...} }
-  }
-]
-```
-
-**Analyze output:**
-```json
-{
-  "file": "path/to/file.ts",
-  "exports": [
-    { "name": "exportName", "kind": "Constant", "line": 139 }
-  ]
-}
-```
-
-## Performance
-
-Each script invocation:
-1. Starts TypeScript Language Server (~300-500ms)
-2. Initializes LSP connection
-3. Opens document
-4. Performs query
-5. Closes and stops
-
-For multiple queries on the same file, use `lsp-analyze` to batch operations in a single session.
-
-## Related Skills
-
-- **code-documentation**: TSDoc standards for documentation