@plaited/development-skills 0.4.1 → 0.6.0

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

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

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