@plaited/development-skills 0.4.1 → 0.6.0

package/{.claude → .plaited}/rules/accuracy.md

@@ -1,6 +1,6 @@
 <!--
-RULE TEMPLATE - Distributed via /scaffold-rules
-Variables: {{LINK:testing}}, {{#if development-skills}}, {{#if supports-slash-commands}}
+RULE TEMPLATE - Distributed via scaffold-rules skill
+Variables: {{LINK:testing}}, {{#if development-skills}}
 -->
 
 # Accuracy and Confidence Standards
@@ -19,7 +19,7 @@ Variables: {{LINK:testing}}, {{#if development-skills}}, {{#if supports-slash-co
 {{#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-refs` to find all usages of a symbol
      - Use `lsp-hover` to verify type signatures
      - Use `lsp-analyze` for batch analysis of file structure
 {{/if}}
@@ -30,14 +30,7 @@ Variables: {{LINK:testing}}, {{#if development-skills}}, {{#if supports-slash-co
 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

package/{.claude → .plaited}/rules/code-review.md

@@ -1,6 +1,6 @@
 <!--
-RULE TEMPLATE - Distributed via /scaffold-rules
-Variables: {{#if development-skills}}, {{#if supports-slash-commands}}
+RULE TEMPLATE - Distributed via scaffold-rules skill
+Variables: {{#if development-skills}}
 -->
 
 # Code Review Standards
@@ -17,16 +17,9 @@ When working with AgentSkills directories (`.claude/skills/`, `.cursor/skills/`,
 
 {{#if development-skills}}
 **Validate structure:**
-{{#if supports-slash-commands}}
-```
-/validate-skill <path>
-```
-{{/if}}
-{{^if supports-slash-commands}}
 ```bash
 bunx @plaited/development-skills validate-skill <path>
 ```
-{{/if}}
 
 This checks:
 - SKILL.md exists with required frontmatter (name, description)
@@ -221,38 +214,6 @@ import config from './config.json'
 
 **Rationale:** Import attributes (ES2025) explicitly declare module types to the runtime. The `with { type: 'json' }` syntax is the standard (replacing the deprecated `assert` keyword). This provides runtime enforcement—if the file isn't valid JSON, the import fails.
 
-## Module Organization
-
-Organize module exports into separate files by category:
-
-```
-module/
-├── module.types.ts      # Type definitions only
-├── module.schemas.ts    # Zod schemas and schema-inferred types
-├── module.constants.ts  # Constants and enum-like objects
-├── module-client.ts     # Implementation
-└── index.ts             # Public API exports (barrel file)
-```
-
-### Key Principles
-
-- **Types file**: Contains only type definitions, does NOT re-export from sibling files
-- **Schemas file**: Contains Zod schemas and their inferred types, does NOT export constants
-- **Constants file**: Contains all constant values (error codes, method names, defaults)
-- **Barrel file**: Uses wildcard exports; non-public files are simply not included
-
-```typescript
-// ✅ Good: Direct imports from specific files
-import type { Config } from './module.types.ts'
-import { ConfigSchema } from './module.schemas.ts'
-import { METHODS, ERROR_CODES } from './module.constants.ts'
-
-// ❌ Avoid: Expecting types file to re-export everything
-import { Config, ConfigSchema, METHODS } from './module.types.ts'
-```
-
-**Rationale:** Prevents circular dependencies, makes dependencies explicit, improves tree-shaking.
-
 ## Documentation Standards
 
 ### Mermaid Diagrams Only

package/.plaited/rules/git-workflow.md

@@ -0,0 +1,36 @@
+<!--
+RULE TEMPLATE - Distributed via scaffold-rules skill
+Variables: {{LINK:*}}
+-->
+
+# Git Workflow
+
+## Commit Message Format
+
+Use multi-line commit messages for detailed changes:
+
+```bash
+git commit -m "refactor: description here
+
+Additional context on second line."
+```
+
+## 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/.plaited/rules/module-organization.md

@@ -0,0 +1,92 @@
+<!--
+RULE TEMPLATE - Distributed via scaffold-rules skill
+Variables: {{#if bun}}
+-->
+
+# Module Organization
+
+## No Index Files
+
+**Never use `index.ts` or `index.js` files.** These create implicit magic and complicate debugging.
+
+### Re-export Pattern
+
+Use named re-export files at the parent level, matching the folder name:
+
+```
+src/
+├── acp/                 # Feature module
+│   ├── acp.types.ts
+│   ├── acp.schemas.ts
+│   └── acp.ts           # Main implementation
+├── acp.ts               # Re-exports public API from acp/
+├── utils/
+│   └── format.ts
+└── utils.ts             # Re-exports public API from utils/
+```
+
+### Single Feature Packages
+
+When a package has one primary feature, expose that re-export file directly as main:
+
+```json
+{
+  "main": "src/acp.ts",
+  "exports": {
+    ".": "./src/acp.ts",
+    "./utils": "./src/utils.ts"
+  }
+}
+```
+
+Only use `main.ts` if the package truly has multiple co-equal entry points that need a unified export.
+
+## Explicit Import Extensions
+
+{{#if bun}}
+Always include `.ts` extensions in imports. Bun runs TypeScript natively—no compilation required:
+{{/if}}
+
+```typescript
+// ✅ Good
+import { Config } from './module.types.ts'
+import { createClient } from '../acp/acp.ts'
+
+// ❌ Avoid
+import { Config } from './module.types'
+```
+
+**Rationale:** Explicit extensions enable direct execution, clearer module graphs, and align with ES module standards. With `allowImportingTsExtensions: true`, TypeScript supports this pattern.
+
+## File Organization Within Modules
+
+```
+feature/
+├── feature.types.ts      # Type definitions only
+├── feature.schemas.ts    # Zod schemas + inferred types
+├── feature.constants.ts  # Constants, error codes
+└── feature.ts            # Main implementation
+```
+
+- **Types file**: Type definitions only, no re-exports from siblings
+- **Schemas file**: Zod schemas and `z.infer<>` types
+- **Constants file**: All constant values
+- **Main file**: Primary implementation, named after the feature
+
+### Key Principles
+
+- **Direct imports**: Import from specific files, not through re-exports within a module
+- **Re-exports at boundaries**: Only use re-export files to expose public API at module boundaries
+- **No circular re-exports**: Types file does NOT re-export from siblings
+
+```typescript
+// ✅ Good: Direct imports from specific files
+import type { Config } from './feature.types.ts'
+import { ConfigSchema } from './feature.schemas.ts'
+import { ERROR_CODES } from './feature.constants.ts'
+
+// ❌ Avoid: Expecting one file to re-export everything
+import { Config, ConfigSchema, ERROR_CODES } from './feature.types.ts'
+```
+
+**Rationale:** Prevents circular dependencies, makes dependencies explicit, improves tree-shaking.

package/{.claude → .plaited}/rules/testing.md

@@ -1,5 +1,5 @@
 <!--
-RULE TEMPLATE - Distributed via /scaffold-rules
+RULE TEMPLATE - Distributed via scaffold-rules skill
 Variables: {{#if agent:claude}}
 -->
 
@@ -75,6 +75,86 @@ If a value might not exist, the test should either:
 2. Assert that it doesn't exist (if that's the expected behavior)
 3. Restructure the test to ensure the value is always present
 
+## Test Coverage Principles
+
+### Expansion Checklist
+
+When writing tests, ensure coverage of:
+
+- [ ] **Happy path** - Expected normal usage
+- [ ] **Edge cases** - Empty strings, special characters, boundary values
+- [ ] **Fallback paths** - What happens when try/catch catches?
+- [ ] **Real dependencies** - Use installed packages (e.g., `@modelcontextprotocol/sdk`) not fake paths
+- [ ] **Category organization** - Group related tests in `describe` blocks
+
+### Meaningful Test Coverage
+
+Tests should verify behavior, not just exercise code. Each test should answer: "What breaks if this test fails?"
+
+**Coverage priorities:**
+1. **Happy path** - Normal expected usage
+2. **Edge cases** - Boundary conditions, empty inputs, unusual formats
+3. **Error paths** - Invalid inputs, missing dependencies, fallback behavior
+4. **Real integrations** - Use actual installed packages when testing module resolution
+
+### Use Real Dependencies
+
+When testing features that interact with packages or the file system, prefer real installed packages over mocked/fake paths:
+
+```typescript
+// ✅ Good: Real scoped package with subpath exports
+test('resolves scoped package subpath', () => {
+  const result = resolveFilePath('@modelcontextprotocol/sdk/client')
+  expect(result).toContain('node_modules/@modelcontextprotocol/sdk')
+})
+
+// ✅ Good: Real package deep subpath
+test('resolves deep subpath with extension', () => {
+  const result = resolveFilePath('@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js')
+  expect(result).toContain('bearerAuth')
+})
+```
+
+### Test Both Branches
+
+When code has conditional logic, try/catch, or fallbacks, test both paths:
+
+```typescript
+describe('package resolution', () => {
+  test('success: resolves existing package', () => {
+    const result = resolveFilePath('typescript')
+    expect(result).toContain('node_modules/typescript')
+  })
+
+  test('fallback: returns cwd path for non-existent package', () => {
+    const result = resolveFilePath('nonexistent-package')
+    expect(result).toBe(join(cwd, 'nonexistent-package'))
+  })
+})
+```
+
+### Organize with Describe Blocks
+
+Group tests by category for better readability and failure diagnosis:
+
+```typescript
+describe('resolveFilePath', () => {
+  describe('absolute paths', () => {
+    test('returns as-is', () => { /* ... */ })
+  })
+
+  describe('relative paths with extension', () => {
+    test('resolves ./ paths', () => { /* ... */ })
+    test('resolves ../ paths', () => { /* ... */ })
+  })
+
+  describe('scoped package specifiers', () => {
+    test('resolves subpath exports', () => { /* ... */ })
+    test('falls back for non-existent', () => { /* ... */ })
+  })
+})
+```
+
 ## Docker Integration Tests
 
 Tests that require external services or API keys can run in Docker containers for consistent, isolated execution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaited/development-skills",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Development skills for Claude Code - TypeScript LSP, code documentation, and validation tools",
   "license": "ISC",
   "engines": {
@@ -21,7 +21,7 @@
   "files": [
     "bin/",
     "src/",
-    ".claude/"
+    ".plaited/"
   ],
   "publishConfig": {
     "access": "public"
@@ -48,6 +48,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.3.11",
+    "@modelcontextprotocol/sdk": "1.22.0",
     "@types/bun": "1.3.6",
     "format-package": "7.0.0",
     "lint-staged": "16.2.7",

package/src/lsp-analyze.ts

@@ -125,7 +125,7 @@ Examples:
     console.error('Error: File path required')
     process.exit(1)
   }
-  const absolutePath = await resolveFilePath(filePath)
+  const absolutePath = resolveFilePath(filePath)
   const uri = `file://${absolutePath}`
   const rootUri = `file://${process.cwd()}`
 
@@ -211,7 +211,7 @@ Examples:
 
     console.log(JSON.stringify(result, null, 2))
   } catch (error) {
-    console.error(`Error: ${error}`)
+    console.error('Error:', error)
     await client.stop()
     process.exit(1)
   }

package/src/lsp-find.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env bun
 /**
- * Search for symbols across the workspace by name
+ * Search for TypeScript symbols across the workspace by name
  *
- * Usage: bun lsp-find.ts <query> [file]
+ * Usage: bun lsp-find.ts <query> <context-file>
  */
 
 import { parseArgs } from 'node:util'
@@ -10,25 +10,9 @@ import { LspClient } from './lsp-client.ts'
 import { resolveFilePath } from './resolve-file-path.ts'
 
 /**
- * Find a default context file when none is provided
+ * Search for TypeScript symbols across the workspace by name
  *
- * @remarks
- * Checks common TypeScript entry points in order of preference
- */
-const findDefaultContextFile = async (): Promise<string | null> => {
-  const candidates = [`${process.cwd()}/src/index.ts`, `${process.cwd()}/src/main.ts`, `${process.cwd()}/index.ts`]
-  for (const candidate of candidates) {
-    if (await Bun.file(candidate).exists()) {
-      return candidate
-    }
-  }
-  return null
-}
-
-/**
- * Search for symbols across the workspace by name
- *
- * @param args - Command line arguments [query, file?]
+ * @param args - Command line arguments [query, context-file]
  */
 export const lspFind = async (args: string[]) => {
   const { positionals } = parseArgs({
@@ -38,10 +22,15 @@ export const lspFind = async (args: string[]) => {
 
   const [query, filePath] = positionals
 
-  if (!query) {
-    console.error('Usage: lsp-find <query> [file]')
-    console.error('  query: Symbol name or partial name to search')
-    console.error('  file: Optional file to open for project context')
+  if (!query || !filePath) {
+    console.error('Error: context-file required')
+    console.error('')
+    console.error('lsp-find searches TypeScript SYMBOLS (functions, types, classes).')
+    console.error('  - Use Glob to find files by pattern')
+    console.error('  - Use Grep to search text content')
+    console.error('  - Use lsp-find <query> <context-file> for symbol search')
+    console.error('')
+    console.error('Provide any .ts file as context-file (e.g., src/app.ts)')
     process.exit(1)
   }
 
@@ -51,15 +40,7 @@ export const lspFind = async (args: string[]) => {
   try {
     await client.start()
 
-    // Open a file to establish project context if provided, otherwise find a default
-    const contextFile = filePath ? await resolveFilePath(filePath) : await findDefaultContextFile()
-
-    if (!contextFile) {
-      console.error('Error: No context file found.')
-      console.error('Provide a file path or ensure src/index.ts, src/main.ts, or index.ts exists.')
-      await client.stop()
-      process.exit(1)
-    }
+    const contextFile = resolveFilePath(filePath)
 
     const file = Bun.file(contextFile)
     if (!(await file.exists())) {
@@ -88,7 +69,7 @@ export const lspFind = async (args: string[]) => {
 
     console.log(JSON.stringify(result, null, 2))
   } catch (error) {
-    console.error(`Error: ${error}`)
+    console.error('Error:', error)
     await client.stop()
     process.exit(1)
   }

package/src/lsp-hover.ts

@@ -38,7 +38,7 @@ export const lspHover = async (args: string[]) => {
     process.exit(1)
   }
 
-  const absolutePath = await resolveFilePath(filePath)
+  const absolutePath = resolveFilePath(filePath)
   const uri = `file://${absolutePath}`
   const rootUri = `file://${process.cwd()}`
 
@@ -75,7 +75,7 @@ export const lspHover = async (args: string[]) => {
       console.log('null')
     }
   } catch (error) {
-    console.error(`Error: ${error}`)
+    console.error('Error:', error)
     await client.stop()
     process.exit(1)
   }

package/src/lsp-references.ts

@@ -38,7 +38,7 @@ export const lspRefs = async (args: string[]) => {
     process.exit(1)
   }
 
-  const absolutePath = await resolveFilePath(filePath)
+  const absolutePath = resolveFilePath(filePath)
   const uri = `file://${absolutePath}`
   const rootUri = `file://${process.cwd()}`
 
@@ -71,7 +71,7 @@ export const lspRefs = async (args: string[]) => {
 
     console.log(JSON.stringify(result, null, 2))
   } catch (error) {
-    console.error(`Error: ${error}`)
+    console.error('Error:', error)
     await client.stop()
     process.exit(1)
   }

package/src/lsp-symbols.ts

@@ -28,7 +28,7 @@ export const lspSymbols = async (args: string[]) => {
     process.exit(1)
   }
 
-  const absolutePath = await resolveFilePath(filePath)
+  const absolutePath = resolveFilePath(filePath)
   const uri = `file://${absolutePath}`
   const rootUri = `file://${process.cwd()}`
 
@@ -61,7 +61,7 @@ export const lspSymbols = async (args: string[]) => {
 
     console.log(JSON.stringify(result, null, 2))
   } catch (error) {
-    console.error(`Error: ${error}`)
+    console.error('Error:', error)
     await client.stop()
     process.exit(1)
   }

package/src/resolve-file-path.ts

@@ -1,52 +1,42 @@
 import { join } from 'node:path'
 
 /**
- * Check if a path looks like a file path (vs a package specifier)
- *
- * @remarks
- * File paths typically contain a `/` and end with a file extension.
- * Package specifiers are bare like `lodash` or scoped like `@org/pkg`.
- * Scoped packages starting with `@` are excluded even if they have extensions.
+ * Check if a path has a source file extension
  */
-const looksLikeFilePath = (path: string): boolean => {
-  // Scoped packages like @org/pkg/file.ts should use Bun.resolve()
-  if (path.startsWith('@')) return false
-  // Contains a slash and ends with a common source file extension
-  return path.includes('/') && /\.(tsx?|jsx?|mjs|cjs|json)$/.test(path)
-}
+const hasSourceExtension = (path: string): boolean => /\.(tsx?|jsx?|mjs|cjs|json)$/.test(path)
 
 /**
  * Resolve a file path to an absolute path
  *
  * @remarks
- * Handles three types of paths:
- * - Absolute paths (starting with `/`) - returned as-is
- * - Relative paths (starting with `.` or looking like `src/foo.ts`) - resolved from cwd
- * - Package export paths (e.g., `plaited/workshop/get-paths.ts`) - resolved via Bun.resolve()
+ * Resolution order:
+ * 1. Absolute paths (starting with `/`) - returned as-is
+ * 2. Explicit relative with extension (`./foo.ts`, `../bar.ts`) - resolved from cwd
+ * 3. Everything else - try Bun.resolveSync(), fallback to cwd
+ *
+ * The "everything else" category includes:
+ * - Package specifiers: `@org/pkg`, `lodash`, `typescript/lib/typescript.js`
+ * - Relative without extension: `./testing` (for package.json exports)
+ * - Implicit relative: `src/foo.ts` (fails Bun.resolveSync, falls back to cwd)
  */
-export const resolveFilePath = async (filePath: string): Promise<string> => {
+export const resolveFilePath = (filePath: string): string => {
   const cwd = process.cwd()
 
-  // Absolute path
+  // Absolute path - return as-is
   if (filePath.startsWith('/')) {
     return filePath
   }
 
-  // Explicit relative path from cwd (starts with . or ..)
-  if (filePath.startsWith('.')) {
-    return join(cwd, filePath)
-  }
-
-  // Implicit relative path (looks like a file path, e.g., src/utils/foo.ts)
-  if (looksLikeFilePath(filePath)) {
+  // Explicit relative with extension - resolve directly from cwd
+  if (filePath.startsWith('.') && hasSourceExtension(filePath)) {
     return join(cwd, filePath)
   }
 
-  // Try package export path resolution
+  // Everything else: try Bun.resolveSync
+  // Handles packages, exports field resolution, and implicit relative paths (via fallback)
   try {
-    return await Bun.resolve(filePath, cwd)
+    return Bun.resolveSync(filePath, cwd)
   } catch {
-    // Fall back to relative path from cwd
     return join(cwd, filePath)
   }
 }