@plaited/development-skills 0.6.2 → 0.6.4

package/.plaited/rules/accuracy.md

@@ -1,57 +1,31 @@
-<!--
-RULE TEMPLATE - Distributed via scaffold-rules skill
-Variables: {{LINK:testing}}, {{#if development-skills}}
--->
+# Accuracy
 
-# Accuracy and Confidence Standards
+**95% confidence threshold** - Report uncertainty rather than guess
 
-**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-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}}
-   - 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
-     - Available via `bunx @plaited/development-skills lsp-*` commands
-{{/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.
+**Verification first** - Read files before stating implementation details
+*Verify:* Did you read the file before commenting on it?
 
 **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}}.
+- State the discrepancy clearly
+- Explain why you can't confidently recommend a fix
+- Present issue to user for resolution
+- Never invent solutions
+
+**TypeScript verification** - Use LSP tools for type-aware analysis:
+- `lsp-find` - Search symbols across workspace
+- `lsp-refs` - Find all usages before modifying
+- `lsp-hover` - Verify type signatures
+- `lsp-analyze` - Batch analysis of file structure
+
+**Dynamic exploration:**
+- Read tool for direct file verification
+- Grep/Glob for content and pattern searches
+- Prioritize live code over cached knowledge
+
+**Agent-specific applications:**
+- Documentation: Only update TSDoc if types match current code
+- Architecture: Verify patterns exist in codebase
+- Code review: Read files before commenting
+- Patterns: Confirm examples reflect actual usage
+
+See .plaited/rules/testing.md for verification in test contexts.

package/.plaited/rules/bun.md

@@ -0,0 +1,29 @@
+# Bun APIs
+
+**Prefer Bun over Node.js** when running in Bun environment.
+
+**File system:**
+- `Bun.file(path).exists()` not `fs.existsSync()`
+- `Bun.file(path).text()` not `readFileSync()`
+- `Bun.write(path, data)` not `writeFileSync()`
+*Verify:* `grep 'from .node:fs' src/`  
+*Fix:* Replace with Bun.file/Bun.write
+
+**Shell commands:**
+- `Bun.$\`cmd\`` not `child_process.spawn()`
+*Verify:* `grep 'child_process' src/`  
+*Fix:* Replace with Bun.$ template literal
+
+**Path resolution:**
+- `Bun.resolveSync()` for module resolution
+- `import.meta.dir` for current directory
+- Keep `node:path` for join/resolve/dirname
+*Verify:* Check for `process.cwd()` misuse
+
+**Executables:**
+- `Bun.which(cmd)` to check if command exists
+- `Bun.$\`bun add pkg\`` for package management
+
+**When Node.js OK:** readline (interactive input), node:path utilities, APIs without Bun equivalents
+
+**Docs:** https://bun.sh/docs

package/.plaited/rules/core.md

@@ -0,0 +1,43 @@
+# Core Conventions
+
+**Type over interface** - `type User = {` instead of `interface User {`
+*Verify:* `lsp-find interface` or `grep 'interface [A-Z]' src/`
+*Fix:* Replace `interface X {` with `type X = {`
+
+**No any types** - Use `unknown` with type guards
+*Verify:* `grep ': any' src/`
+*Fix:* Replace `any` with `unknown`, add type guard
+
+**PascalCase types** - `type UserConfig`, schemas get `Schema` suffix: `UserConfigSchema`
+*Verify:* `lsp-find` for lowercase type names
+*Fix:* Rename to PascalCase
+
+**Arrow functions** - Prefer `const fn = () =>` over `function fn()`
+*Verify:* `grep 'function \w' src/`
+*Fix:* Convert to arrow function
+
+**Object params >2 args** - `fn({ a, b, c }: { ... })` not `fn(a, b, c)`
+*Exception:* CLI entry points take `args: string[]`
+*Verify:* Review function signatures with `lsp-hover`
+
+**Private fields** - Use `#field` (ES2022) not `private field` (TypeScript)
+*Verify:* `grep 'private \w' src/`
+*Fix:* Replace `private x` with `#x`
+
+**JSON imports** - `import x from 'file.json' with { type: 'json' }`
+*Verify:* `grep "from.*\.json['\"]" src/` (check for missing `with`)
+*Fix:* Add `with { type: 'json' }`
+
+**@ts-ignore needs description** - `// @ts-ignore - reason here`
+*Verify:* `grep '@ts-ignore' src/` (check for missing comment)
+
+**Short-circuit/ternary OK** - `condition && doSomething()` is acceptable
+
+**Empty interface extending single** - `interface Custom extends Base {}` is OK for branded types
+
+**Mermaid diagrams only** - No ASCII box-drawing in markdown
+*Verify:* `grep '[┌│└─]' *.md`
+
+**No @example in TSDoc** - Tests are living examples
+
+**AgentSkills validation** - `bunx @plaited/development-skills validate-skill <path>`

package/.plaited/rules/documentation.md

@@ -1,41 +1,23 @@
-# Documentation Standards
+# Documentation
 
-## TSDoc Requirements
-
-Public APIs require comprehensive TSDoc documentation following these conventions:
-
-- **No `@example` sections** - Tests serve as living examples
-- **Use `@internal` marker** - Mark non-public APIs explicitly
-- **Always use `type`** - Prefer type aliases over interfaces
-
-### TSDoc Template
+**TSDoc required** for public APIs
 
+**Template:**
 ```typescript
 /**
- * Brief description of what this does
+ * Brief description
  *
  * @remarks
- * Additional context, usage notes, or implementation details.
+ * Additional context
  *
- * @param options - Description of the parameter
- * @returns Description of return value
+ * @param options - Description
+ * @returns Description
  *
  * @public
  */
 ```
 
-## Diagrams
-
-Use Mermaid diagrams only (not ASCII art):
-
-```markdown
-\```mermaid
-flowchart TD
-    A[Start] --> B[Process]
-    B --> C[End]
-\```
-```
-
-**Avoid**: ASCII box-drawing characters (`┌`, `│`, `└`, `─`, etc.)
-
-**Rationale:** Token efficiency, clearer semantic meaning, easier maintenance.
+**No @example** - Tests are living examples  
+**Use @internal** - Mark non-public APIs  
+**Mermaid only** - No ASCII box-drawing diagrams  
+*Verify:* `grep '[┌│└─]' *.md`

package/.plaited/rules/modules.md

@@ -0,0 +1,27 @@
+# Module Organization
+
+**No index.ts** - Never use index files, they create implicit magic  
+*Verify:* `find . -name 'index.ts'`  
+*Fix:* Rename to feature name: `feature/index.ts` → `feature.ts` at parent level
+
+**Explicit .ts extensions** - `import { x } from './file.ts'` not `'./file'`  
+*Verify:* `grep "from '\./.*[^s]'" src/` (imports without .ts)  
+*Fix:* Add `.ts` extension
+
+**Re-export at boundaries** - Parent `feature.ts` re-exports from `feature/feature.ts`
+```
+src/
+├── acp/           # Feature module
+│   └── acp.ts     # Implementation
+└── acp.ts         # Re-exports public API
+```
+
+**File organization within modules:**
+- `feature.types.ts` - Type definitions only
+- `feature.schemas.ts` - Zod schemas + `z.infer<>` types
+- `feature.constants.ts` - Constants, error codes
+- `feature.ts` - Main implementation
+
+**Direct imports** - Import from specific files, not through re-exports within module  
+*Verify:* Check for circular imports  
+*Fix:* Import directly: `from './feature.types.ts'` not `from './feature.ts'`

package/.plaited/rules/testing.md

@@ -1,200 +1,30 @@
 # Testing
 
-Use Bun's built-in test runner for unit and integration tests.
+**Use test not it** - `test('description', ...)` instead of `it('...')`  
+*Verify:* `grep '\bit(' src/**/*.spec.ts`  
+*Fix:* Replace `it(` with `test(`
 
-## Test Types
+**No conditional assertions** - Never `if (x) expect(x.value)`  
+*Verify:* `grep 'if.*expect\|&&.*expect' src/**/*.spec.ts`  
+*Fix:* Assert condition first: `expect(x).toBeDefined(); expect(x.value)...`
 
-### Unit/Integration Tests (`*.spec.ts`)
+**Test both branches** - Try/catch, conditionals, fallbacks need both paths tested  
+*Verify:* Review test coverage for error paths  
+*Fix:* Add test for catch block, else branch, fallback case
 
-Standard Bun tests using `*.spec.ts` extension:
-- Run with `bun test` command
-- Used for testing business logic, utilities, and non-visual functionality
+**Use real dependencies** - Prefer installed packages over mocks when testing module resolution  
+*Verify:* Review test imports for fake paths  
+*Fix:* Use actual package like `@modelcontextprotocol/sdk/client`
 
-## Running Tests
+**Organize with describe** - Group related tests in `describe('feature', () => {...})`  
+*Verify:* Check for flat test structure  
+*Fix:* Add describe blocks by category (happy path, edge cases, errors)
 
-```bash
-# Run all unit tests
-bun test
+**Coverage checklist** - Happy path, edge cases, error paths, real integrations  
+*Verify:* Review test file completeness
 
-# Run a specific spec test file
-bun test path/to/file.spec.ts
+**Docker tests** - `*.docker.ts` for external APIs, run via docker-compose  
+*Verify:* Check if test needs API key or external service  
+*Fix:* Rename to `.docker.ts`, update CI gating
 
-# Run tests matching a pattern
-bun test pattern
-```
-
-## Test Style Conventions
-
-### Use `test` Instead of `it`
-
-Use `test` instead of `it` in test files for consistency:
-
-```typescript
-// ✅ Good
-test('should create ACP client correctly', () => {
-  // ...
-})
-
-// ❌ Avoid
-it('should create ACP client correctly', () => {
-  // ...
-})
-```
-
-## Anti-Patterns
-
-### No Conditionals Around Assertions
-
-Never wrap assertions in conditionals. Tests should fail explicitly, not silently skip assertions.
-
-```typescript
-// ❌ WRONG: Conditional assertion
-if (result) {
-  expect(result.value).toBe(expected)
-}
-
-// ❌ WRONG: Optional chaining with assertion
-result?.value && expect(result.value).toBe(expected)
-
-// ✅ CORRECT: Assert the condition, then assert the value
-expect(result).toBeDefined()
-expect(result.value).toBe(expected)
-
-// ✅ CORRECT: Use type narrowing assertion
-expect(result).not.toBeNull()
-expect(result!.value).toBe(expected)
-```
-
-If a value might not exist, the test should either:
-1. Assert that it exists first, then check its value
-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.
-
-### File Naming
-
-- **`*.docker.ts`**: Tests that run in Docker containers
-- These are excluded from `bun test` and run separately via Docker Compose
-
-### Running Docker Tests
-
-```bash
-# Run with Docker Compose (requires API key)
-ANTHROPIC_API_KEY=sk-... docker compose -f docker-compose.test.yml run --rm test
-
-# Or using an npm script if configured
-ANTHROPIC_API_KEY=sk-... bun run test:docker
-```
-
-### CI Workflow Pattern
-
-Docker tests can use path filtering to reduce API costs:
-
-```yaml
-# .github/workflows/ci.yml
-jobs:
-  changes:
-    # Detects which paths changed
-    steps:
-      - uses: dorny/paths-filter@v3
-        with:
-          filters: |
-            integration:
-              - 'src/**'
-
-  test-integration:
-    needs: changes
-    if: ${{ needs.changes.outputs.integration == 'true' }}
-    # Only runs when src/ files change
-```
-
-### When to Use Docker Tests
-
-Use Docker for tests that:
-- Require external API calls (Anthropic, OpenAI, etc.)
-- Need specific environment configurations
-- Should be isolated from the local development environment
-- Are expensive to run and should be gated in CI
+**Run:** `bun test` before commit

package/.plaited/rules/workflow.md

@@ -0,0 +1,40 @@
+# Workflow
+
+## Git Commits
+
+**Conventional commits** - `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, `test:`  
+**Multi-line messages** - Use for detailed context  
+**Never --no-verify** - Fix the issue, don't bypass hooks  
+*Verify:* Check git log format
+
+## GitHub CLI
+
+**Use `gh` over WebFetch** - Better data access, auth, private repos
+
+**PR evaluation** - Fetch ALL sources:
+```bash
+# 1. Comments/reviews
+gh pr view <n> --repo <owner>/<repo> --json title,body,comments,reviews,state
+
+# 2. Security alerts
+gh api repos/<owner>/<repo>/code-scanning/alerts
+
+# 3. Inline comments
+gh api repos/<owner>/<repo>/pulls/<n>/comments
+```
+
+**PR checklist:**
+- [ ] Human reviewer comments
+- [ ] AI code review comments  
+- [ ] Security alerts (ReDoS, injection)
+- [ ] Code quality comments
+- [ ] Inline suggestions
+
+**URL patterns:**
+| URL | Command |
+|-----|---------|
+| `github.com/.../pull/<n>` | `gh pr view <n> --repo ...` |
+| `github.com/.../issues/<n>` | `gh issue view <n> --repo ...` |
+| `.../security/code-scanning/<id>` | `gh api .../code-scanning/alerts/<id>` |
+
+**Review states:** `APPROVED`, `CHANGES_REQUESTED`, `COMMENTED`, `PENDING`

package/.plaited/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/.plaited/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