@plaited/development-skills 0.3.5

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

@@ -0,0 +1,47 @@
+---
+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

@@ -0,0 +1,113 @@
+# 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

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

@@ -0,0 +1,164 @@
+# Documentation Maintenance
+
+Guidelines for maintaining documentation hygiene: synchronizing TSDoc with code, removing non-compliant comments, and handling orphaned documentation.
+
+## Comment Policy
+
+### Allowed Comments
+
+1. **TSDoc comment blocks** following project standards
+2. **TODO comments**: `// TODO: description of future work`
+3. **FIXME comments**: `// FIXME: description of issue to fix`
+
+### Remove These Comments
+
+1. **Performance notes**: `// Performance: this is O(n)`
+2. **Update timestamps**: `// Updated 2024-12-15 to fix bug`
+3. **Historical notes**: `// This used to use Array.filter`
+4. **Implementation notes**: `// Hack to work around limitation`
+5. **Inline explanations**: `// Loop through items and process`
+6. **Rationale comments**: `// We do this because...`
+
+### Convert to TSDoc
+
+Valuable information from inline comments should be moved to TSDoc `@remarks`:
+
+```typescript
+// This function is O(n) because it iterates all items
+// We use a for-loop instead of .filter for better performance
+
+// ↓ CONVERT TO ↓
+
+/**
+ * @internal
+ * Processes items with linear complexity.
+ *
+ * @remarks
+ * - Complexity: O(n) where n is number of items
+ * - Uses for-loop instead of .filter for performance
+ */
+```
+
+## Synchronization Tasks
+
+### Parameter Sync
+
+```typescript
+// OUT OF SYNC:
+/**
+ * @param name - User name
+ * @param age - User age
+ */
+function createUser({ username, age }: UserData) { ... }
+
+// FIXED:
+/**
+ * @param options - User data
+ * @param options.username - User's username
+ * @param options.age - User's age
+ */
+function createUser({ username, age }: UserData) { ... }
+```
+
+### Return Type Sync
+
+```typescript
+// OUT OF SYNC:
+/**
+ * @returns User object
+ */
+function getUser(): Promise<User> { ... }
+
+// FIXED:
+/**
+ * @returns Promise resolving to User object
+ */
+function getUser(): Promise<User> { ... }
+```
+
+### Generic Parameter Sync
+
+```typescript
+// OUT OF SYNC:
+/**
+ * @template T - Generic type
+ */
+function process<T extends BaseType>() { ... }
+
+// FIXED:
+/**
+ * @template T - Type extending BaseType for processing
+ */
+function process<T extends BaseType>() { ... }
+```
+
+## Orphaned Documentation
+
+When TSDoc comments reference code that no longer exists:
+
+1. **Deleted functions/types**: Remove the entire TSDoc block
+2. **Moved code**: Report the TSDoc location and ask where code moved to
+3. **Invalid @see references**: Remove `@see` tags referencing deleted code
+4. **Uncertain**: If confidence < 95%, report for manual review
+
+**Examples:**
+
+```typescript
+// ORPHANED: Function deleted, TSDoc remains
+/**
+ * @deprecated Use newFunction instead
+ * @param x - Input value
+ */
+// <--- Nothing here, function was deleted
+
+// ACTION: Remove entire TSDoc block
+
+// INVALID REFERENCE: @see points to deleted code
+/**
+ * Processes user data.
+ * @see {@link validateInput} - Function no longer exists
+ * @see {@link sanitizeData} - Still exists
+ */
+function processUser(data: UserData) { ... }
+
+// ACTION: Remove @see for validateInput, keep sanitizeData reference
+```
+
+## Maintenance Process
+
+When cleaning documentation in a file or directory:
+
+1. **Scan for comments**
+   - Identify all comment types (TSDoc, inline, TODO/FIXME)
+   - Classify each comment (KEEP, REMOVE, CONVERT)
+
+2. **Remove non-compliant**
+   - Delete performance notes, timestamps, historical notes
+   - Remove inline explanations and implementation details
+
+3. **Remove orphaned TSDoc**
+   - Delete TSDoc blocks for deleted functions/types
+   - Remove invalid @see references to deleted code
+   - Report uncertain cases for manual review
+
+4. **Update TSDoc blocks**
+   - Sync parameter names and types
+   - Update return type descriptions
+   - Verify generic parameter documentation
+
+5. **Convert valuable inline to TSDoc**
+   - Move complexity notes to @remarks
+   - Move important context to @remarks
+
+6. **Validate completeness**
+   - All public exports have TSDoc
+   - All public APIs have @param/@returns
+   - Types have @property for all properties
+   - @internal marker on non-public code
+
+## Safety Guidelines
+
+1. **Start small** - Test on one file before batch processing
+2. **Review changes** - Examine diffs before committing
+3. **Preserve TODOs** - Never remove TODO/FIXME comments
+4. **No code changes** - Only modify comments and TSDoc

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

@@ -0,0 +1,100 @@
+# 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

@@ -0,0 +1,116 @@
+# 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

@@ -0,0 +1,60 @@
+# 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

@@ -0,0 +1,97 @@
+---
+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
+
+## 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?"