@plaited/development-skills 0.3.5

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

@@ -0,0 +1,66 @@
+---
+description: Analyze a TypeScript file structure, exports, and symbols
+allowed-tools: Bash
+---
+
+# LSP Analyze
+
+Batch analysis of a TypeScript/JavaScript file. Get an overview of exports, symbols, and optionally type info at specific positions.
+
+**Arguments:** $ARGUMENTS
+
+## Usage
+
+```
+/lsp-analyze <file> [options]
+```
+
+Options:
+- `--symbols` or `-s`: List all symbols
+- `--exports` or `-e`: List only exported symbols (default if no options)
+- `--hover <line:char>`: Get type info at position (repeatable)
+- `--refs <line:char>`: Find references at position (repeatable)
+- `--all`: Run symbols + exports analysis
+
+## Instructions
+
+### Step 1: Parse Arguments
+
+Extract file path and options from `$ARGUMENTS`.
+
+If file is missing, show usage:
+```
+Usage: /lsp-analyze <file> [options]
+
+Examples:
+  /lsp-analyze src/utils/parser.ts --exports
+  /lsp-analyze src/lib/config.ts --all
+  /lsp-analyze src/index.ts --hover 50:10 --refs 60:5
+```
+
+Default to `--exports` if no options provided.
+
+### Step 2: Run LSP Analyze
+
+Execute the development-skills CLI command:
+```bash
+bunx @plaited/development-skills lsp-analyze <file> [options]
+```
+
+### Step 3: Format Output
+
+Parse the JSON output and present in a structured format:
+
+**File:** `<file>`
+
+**Exports:**
+| Name | Kind | Line |
+|------|------|------|
+| ... | ... | ... |
+
+**Symbols:** (if requested)
+| Name | Kind | Line |
+|------|------|------|
+| ... | ... | ... |
+
+For hover/refs results, format as described in the individual commands.

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

@@ -0,0 +1,51 @@
+---
+description: Search for TypeScript symbols across the workspace by name
+allowed-tools: Bash
+---
+
+# LSP Find
+
+Search for symbols (functions, types, classes, variables) across the TypeScript/JavaScript codebase.
+
+**Arguments:** $ARGUMENTS
+
+## Usage
+
+```
+/lsp-find <query> [context-file]
+```
+
+- `query`: Symbol name or partial name to search for
+- `context-file`: Optional file to open for project context
+
+## Instructions
+
+### Step 1: Parse Arguments
+
+Extract query and optional context file from `$ARGUMENTS`.
+
+If query is missing, show usage:
+```
+Usage: /lsp-find <query> [context-file]
+
+Examples:
+  /lsp-find bElement
+  /lsp-find useTemplate src/main/use-template.ts
+```
+
+### Step 2: Run LSP Find
+
+Execute the development-skills CLI command:
+```bash
+bunx @plaited/development-skills lsp-find <query> [context-file]
+```
+
+### Step 3: Format Output
+
+Parse the JSON output and present results as a table:
+
+| Symbol | Kind | File | Line |
+|--------|------|------|------|
+| ... | ... | ... | ... |
+
+Group results by file if there are many matches. Highlight the most relevant matches (exact name matches first).

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

@@ -0,0 +1,48 @@
+---
+description: Get TypeScript type information at a specific position in a file
+allowed-tools: Bash
+---
+
+# LSP Hover
+
+Get type information at a specific position in a TypeScript/JavaScript file.
+
+**Arguments:** $ARGUMENTS
+
+## 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

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

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

@@ -0,0 +1,29 @@
+---
+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/accuracy.md

@@ -0,0 +1,64 @@
+<!--
+RULE TEMPLATE - Distributed via /scaffold-rules
+Variables: {{LINK:testing}}, {{#if development-skills}}, {{#if supports-slash-commands}}
+-->
+
+# Accuracy and Confidence Standards
+
+**Confidence Threshold**: 95% - Report uncertainty rather than guess
+
+## Verification Protocol
+
+1. **Verification First**: Before stating any specific implementation detail (function signature, file path, API schema), read the relevant file in real-time to verify accuracy.
+
+2. **Handling Uncertainty**: If you cannot verify information or find contradictions between instructions and live code, you must NOT provide speculative answers.
+   - **Action**: Clearly state you cannot answer with high confidence and explain the discrepancy.
+   - Example: "I cannot confirm [detail] because my instructions indicate [X], but the current file shows [Y]. My knowledge may be outdated."
+
+3. **Dynamic Exploration**:
+{{#if development-skills}}
+   - **For TypeScript/JavaScript projects**: When @plaited/development-skills is installed, prefer LSP tools for type-aware verification:
+     - Use `lsp-find` to search for symbols, types, and patterns across the workspace
+     - Use `lsp-references` to find all usages of a symbol
+     - Use `lsp-hover` to verify type signatures
+     - Use `lsp-analyze` for batch analysis of file structure
+{{/if}}
+   - Use Read tool for direct file verification
+   - Use Grep/Glob for content and pattern searches
+   - Always prioritize live code over instructions
+
+4. **Tool-Assisted Verification**: Use available tools to enhance verification accuracy:
+{{#if development-skills}}
+   - **TypeScript LSP tools** (when available): Use for type-aware analysis of `.ts`, `.tsx`, `.js`, `.jsx` files
+{{/if}}
+{{#if supports-slash-commands}}
+     - Available via `/lsp-hover`, `/lsp-find`, `/lsp-refs`, `/lsp-analyze` commands
+{{/if}}
+{{^if supports-slash-commands}}
+{{#if development-skills}}
+     - Available via `bunx @plaited/development-skills lsp-*` commands
+{{/if}}
+{{/if}}
+   - **WebFetch**: Retrieve current documentation from authoritative sources (MDN Web Docs, WHATWG specs) when using web platform APIs
+   - These tools complement (but do not replace) reading live code - always verify outputs against actual implementation
+
+## Certainty Requirements
+
+You may only propose a specific change if you are **at least 95% certain** it is correct, based on direct comparison with current code.
+
+**When uncertain:**
+- Report the discrepancy clearly
+- State why you cannot confidently recommend a fix
+- Present the issue to the user for manual resolution
+- DO NOT invent solutions or infer changes
+
+## For Agent-Specific Applications
+
+Agents should apply these standards to their specific domain:
+
+- **Documentation agents**: Only update TSDoc if parameter names/types match current code
+- **Architecture agents**: Verify referenced patterns exist in current codebase
+- **Code review agents**: Read files before commenting on implementation details
+- **Pattern agents**: Confirm examples reflect actual usage in codebase
+
+For verification in test contexts, see {{LINK:testing}}.

package/.claude/rules/bun-apis.md

@@ -0,0 +1,80 @@
+# Bun Platform APIs
+
+**IMPORTANT**: Prefer Bun's native APIs over Node.js equivalents when running in the Bun environment.
+
+## File System Operations
+
+- ✅ Use `Bun.file(path).exists()` instead of `fs.existsSync()`
+- ✅ Use `Bun.file(path)` API for reading/writing files
+- ✅ Use `Bun.write()` for efficient file writes
+
+```typescript
+// ✅ Good: Bun APIs
+const exists = await Bun.file('config.json').exists()
+const content = await Bun.file('data.txt').text()
+await Bun.write('output.json', JSON.stringify(data))
+
+// ❌ Avoid: Node.js equivalents
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+const exists = existsSync('config.json')
+```
+
+## Shell Commands
+
+- ✅ Use `Bun.$` template literal for shell commands
+- ❌ Avoid `child_process.spawn()` or `child_process.exec()`
+
+```typescript
+// ✅ Good: Bun shell
+await Bun.$`npm install`
+const result = await Bun.$`git status`.text()
+
+// ❌ Avoid: Node.js child_process
+import { spawn } from 'node:child_process'
+spawn('npm', ['install'])
+```
+
+## Path Resolution
+
+- ✅ Use `Bun.resolveSync()` for module resolution
+- ✅ Use `import.meta.dir` for current directory
+- ⚠️ Keep `node:path` utilities for path manipulation (join, resolve, dirname)
+
+```typescript
+// ✅ Good: Bun + node:path combo
+import { join } from 'node:path'
+const configPath = join(import.meta.dir, 'config.json')
+const resolved = Bun.resolveSync('./module', import.meta.dir)
+```
+
+## Package Management
+
+- ✅ Use `Bun.which(cmd)` to check for executables
+- ⚠️ No programmatic package manager API yet - use CLI commands via `Bun.$`
+
+```typescript
+// ✅ Good: Check for executable
+const bunPath = Bun.which('bun')
+if (!bunPath) throw new Error('bun not found')
+
+// Install packages via shell
+await Bun.$`bun add zod`
+```
+
+## Environment Detection
+
+- ✅ Check `typeof Bun !== 'undefined'` for Bun runtime
+- ✅ Use `Bun.which('bun')` to verify bun executable exists
+
+## When to Use Node.js APIs
+
+- Interactive input (readline)
+- Complex path manipulation (prefer `node:path` utilities)
+- APIs without Bun equivalents
+
+## Documentation
+
+- Main docs: https://bun.sh/docs
+- Shell API: https://bun.sh/docs/runtime/shell
+- File I/O: https://bun.sh/docs/api/file-io
+- Runtime APIs: https://bun.sh/docs/runtime/bun-apis