@plaited/development-skills 0.5.0 → 0.6.0

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

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