@plaited/development-skills 0.3.5

package/.claude/rules/code-review.md

@@ -0,0 +1,276 @@
+<!--
+RULE TEMPLATE - Distributed via /scaffold-rules
+Variables: {{#if development-skills}}, {{#if supports-slash-commands}}
+-->
+
+# Code Review Standards
+
+The following standards are not automatically enforced by Biome but should be checked during code review.
+
+## Automated Validation
+
+Before completing a code review, run these validation scripts:
+
+### AgentSkills Validation
+
+When working with AgentSkills directories (`.claude/skills/`, `.cursor/skills/`, `.factory/skills/`, etc.):
+
+{{#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)
+- Proper naming conventions
+- Valid markdown references
+{{/if}}
+
+{{^if development-skills}}
+Manually verify:
+- SKILL.md exists with required frontmatter (name, description)
+- Directory name matches skill name
+- All referenced files exist
+{{/if}}
+
+## TypeScript Style Conventions
+
+### Prefer `type` Over `interface`
+
+Use type aliases instead of interfaces for better consistency and flexibility:
+
+```typescript
+// ✅ Good
+type User = {
+  name: string
+  email: string
+}
+
+// ❌ Avoid
+interface User {
+  name: string
+  email: string
+}
+```
+
+**Rationale:** Type aliases are more flexible (unions, intersections, mapped types) and provide consistent syntax across the codebase.
+
+### No `any` Types
+
+Always use proper types; use `unknown` if type is truly unknown and add type guards:
+
+```typescript
+// ✅ Good
+const process = (data: unknown) => {
+  if (typeof data === 'string') {
+    return data.toUpperCase()
+  }
+}
+
+// ❌ Avoid
+const process = (data: any) => {
+  return data.toUpperCase()
+}
+```
+
+### PascalCase for Types and Schemas
+
+All type names use PascalCase. Zod schema names use `PascalCaseSchema` suffix:
+
+```typescript
+// ✅ Good
+type UserConfig = { /* ... */ }
+const UserConfigSchema = z.object({ /* ... */ })
+
+// ❌ Avoid
+type userConfig = { /* ... */ }
+const zUserConfig = z.object({ /* ... */ })  // Don't use z-prefix
+```
+
+### Arrow Functions Preferred
+
+```typescript
+// ✅ Good
+const greet = (name: string) => `Hello, ${name}!`
+
+// ❌ Avoid
+function greet(name: string) {
+  return `Hello, ${name}!`
+}
+```
+
+### Object Parameter Pattern
+
+For functions with more than two parameters, use a single object parameter:
+
+```typescript
+// ✅ Good: Object parameter pattern
+const createClient = ({
+  command,
+  timeout,
+  cwd,
+}: {
+  command: string[]
+  timeout: number
+  cwd?: string
+}): ACPClient => { /* ... */ }
+
+// ❌ Avoid: Multiple positional parameters
+const createClient = (
+  command: string[],
+  timeout: number,
+  cwd?: string
+): ACPClient => { /* ... */ }
+```
+
+## TypeScript Comment Directives
+
+### `@ts-ignore` Requires Description
+
+- When using `@ts-ignore`, always include a description explaining why the type error is being suppressed
+- This helps future maintainers understand the reasoning
+- Example:
+  ```typescript
+  // @ts-ignore - TypeScript incorrectly infers this as string when it's actually a number from the API
+  const value = response.data
+  ```
+
+**Rationale:** Lost TypeScript-ESLint rule `ban-ts-comment` with `allow-with-description` option during Biome migration
+
+## Expression Statements
+
+### Allow Short-Circuit and Ternary Expressions
+
+- Short-circuit evaluation is acceptable: `condition && doSomething()`
+- Ternary expressions are acceptable: `condition ? doThis() : doThat()`
+- These patterns are idiomatic and improve code readability
+
+**Rationale:** Lost TypeScript-ESLint rule `no-unused-expressions` with `allowShortCircuit` and `allowTernary` options during Biome migration
+
+## Empty Object Types
+
+### Allow Empty Object Types When Extending a Single Interface
+
+- Empty object types are acceptable when they extend exactly one other interface
+- This pattern is useful for creating branded types or extending third-party interfaces
+- Example:
+  ```typescript
+  // ✅ Acceptable: Extends single interface
+  interface CustomElement extends HTMLElement {}
+
+  // ❌ Avoid: Empty with no extends or multiple extends
+  interface Empty {}
+  interface Multi extends Foo, Bar {}
+  ```
+
+**Rationale:** Lost TypeScript-ESLint rule `no-empty-object-type` with `allowInterfaces: 'with-single-extends'` option during Biome migration
+
+## Modern JavaScript Standards
+
+### Prefer Private Fields Over `private` Keyword
+
+Use JavaScript private fields (`#field`) instead of TypeScript's `private` keyword:
+
+```typescript
+// ✅ Good: JavaScript private fields (ES2022+)
+class EventBus {
+  #listeners = new Map<string, Set<Function>>()
+  #count = 0
+
+  #emit(event: string) {
+    this.#count++
+    this.#listeners.get(event)?.forEach(fn => fn())
+  }
+}
+
+// ❌ Avoid: TypeScript private keyword
+class EventBus {
+  private listeners = new Map<string, Set<Function>>()
+  private count = 0
+
+  private emit(event: string) {
+    this.count++
+    this.listeners.get(event)?.forEach(fn => fn())
+  }
+}
+```
+
+**Rationale:** JavaScript private fields are a runtime feature (ES2022) providing true encapsulation. TypeScript's `private` is erased at compile time and can be bypassed. Prefer platform standards over TypeScript-only features
+
+### JSON Import Attributes
+
+Use import attributes when importing JSON files. This is required because the tsconfig uses `verbatimModuleSyntax: true` without `resolveJsonModule`:
+
+```typescript
+// ✅ Good: Import attribute for JSON
+import { version } from '../package.json' with { type: 'json' }
+import config from './config.json' with { type: 'json' }
+
+// ❌ Avoid: Missing import attribute
+import { version } from '../package.json'
+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
+
+Use [mermaid](https://mermaid.js.org/) syntax for all diagrams in markdown files:
+
+```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` Sections in TSDoc
+
+Tests serve as living examples. Do not add `@example` sections to TSDoc comments.

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

@@ -0,0 +1,66 @@
+<!--
+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/rules/github.md

@@ -0,0 +1,154 @@
+# GitHub Integration
+
+## Prefer GitHub CLI Over Web Fetch
+
+When given GitHub URLs (PRs, issues, repos), use the `gh` CLI instead of WebFetch for more reliable and complete data access.
+
+### PR Information
+
+```bash
+# Get PR details with comments and reviews (comprehensive)
+gh pr view <number> --repo <owner>/<repo> --json title,body,comments,reviews,reviewRequests,state,author,additions,deletions,changedFiles
+
+# Get PR diff
+gh pr diff <number> --repo <owner>/<repo>
+
+# Get PR files changed
+gh pr view <number> --repo <owner>/<repo> --json files
+
+# Get PR checks status
+gh pr checks <number> --repo <owner>/<repo>
+```
+
+### Complete PR Evaluation Workflow
+
+When asked to evaluate PR feedback, you MUST fetch **all** feedback sources. Do not just fetch comments/reviews - also check security alerts and inline code comments.
+
+**Step 1: Fetch PR comments and reviews**
+```bash
+gh pr view <number> --repo <owner>/<repo> --json title,body,comments,reviews,state
+```
+
+**Step 2: Fetch code scanning alerts (security vulnerabilities)**
+```bash
+gh api repos/<owner>/<repo>/code-scanning/alerts --jq '
+  .[] | select(.state == "open") | {
+    number: .number,
+    rule: .rule.description,
+    severity: .rule.severity,
+    file: .most_recent_instance.location.path,
+    line: .most_recent_instance.location.start_line
+  }
+'
+```
+
+**Step 3: Fetch inline review comments (code quality, suggestions)**
+```bash
+gh api repos/<owner>/<repo>/pulls/<number>/comments --jq '
+  .[] | {
+    id: .id,
+    user: .user.login,
+    file: .path,
+    line: .line,
+    body: .body
+  }
+'
+```
+
+**Step 4: Address ALL feedback**
+Create a checklist and address each item:
+- [ ] Human reviewer comments
+- [ ] Claude Code review comments
+- [ ] GitHub Advanced Security alerts (ReDoS, injection, etc.)
+- [ ] GitHub Code Quality comments (dead code, useless assignments)
+- [ ] Inline review suggestions
+
+### Comment Sources
+
+| Source | API/Location | Description |
+|--------|--------------|-------------|
+| Human reviewers | `gh pr view --json reviews` | Code owners, team members |
+| Claude Code | `gh pr view --json comments` | AI-generated review (login: `claude`) |
+| GitHub Advanced Security | `gh api .../code-scanning/alerts` | Security vulnerabilities (ReDoS, injection) |
+| GitHub Code Quality | `gh api .../pulls/.../comments` | Code quality issues (login: `github-code-quality[bot]`) |
+| Inline suggestions | `gh api .../pulls/.../comments` | Line-specific review comments |
+
+### Filtering by Author
+
+```bash
+# Get all automated reviews from PR
+gh pr view <number> --repo <owner>/<repo> --json reviews --jq '
+  .reviews[] | select(.author.login | test("github-|claude")) | {author: .author.login, state: .state}
+'
+
+# Get specific inline comment by ID
+gh api repos/<owner>/<repo>/pulls/<number>/comments --jq '
+  .[] | select(.id == <comment_id>)
+'
+```
+
+### URL Patterns for Specific Feedback
+
+| URL Pattern | How to Fetch |
+|-------------|--------------|
+| `.../pull/<n>#issuecomment-<id>` | `gh pr view <n> --json comments` |
+| `.../pull/<n>#discussion_r<id>` | `gh api repos/.../pulls/<n>/comments` |
+| `.../security/code-scanning/<id>` | `gh api repos/.../code-scanning/alerts/<id>` |
+
+### Review States
+- `APPROVED` - Reviewer approved changes
+- `CHANGES_REQUESTED` - Reviewer requested changes
+- `COMMENTED` - Review with comments only
+- `PENDING` - Review not yet submitted
+
+### Issue Information
+
+```bash
+# Get issue details
+gh issue view <number> --repo <owner>/<repo> --json title,body,comments,state,author
+
+# List issues
+gh issue list --repo <owner>/<repo> --json number,title,state
+```
+
+### Repository Information
+
+```bash
+# Get repo info
+gh repo view <owner>/<repo> --json name,description,url
+
+# List workflows
+gh workflow list --repo <owner>/<repo>
+
+# View run logs
+gh run view <run-id> --repo <owner>/<repo> --log
+```
+
+### URL Parsing
+
+When given a GitHub URL, extract the components:
+
+| URL Pattern | Command |
+|-------------|---------|
+| `github.com/<owner>/<repo>/pull/<number>` | `gh pr view <number> --repo <owner>/<repo>` |
+| `github.com/<owner>/<repo>/issues/<number>` | `gh issue view <number> --repo <owner>/<repo>` |
+| `github.com/<owner>/<repo>` | `gh repo view <owner>/<repo>` |
+| `github.com/<owner>/<repo>/actions/runs/<id>` | `gh run view <id> --repo <owner>/<repo>` |
+
+### JSON Output Fields
+
+Common useful JSON fields for PRs:
+- `title`, `body`, `state`, `author`
+- `comments` - PR comments
+- `reviews` - Review comments and approvals
+- `additions`, `deletions`, `changedFiles`
+- `files` - List of changed files
+- `commits` - Commit history
+
+### Benefits Over WebFetch
+
+1. **Complete data** - Access to all comments, reviews, and metadata
+2. **Authentication** - Uses configured GitHub credentials
+3. **Structured output** - JSON format for reliable parsing
+4. **No rate limiting issues** - Authenticated requests have higher limits
+5. **Access to private repos** - Works with repos you have access to

package/.claude/rules/testing.md

@@ -0,0 +1,125 @@
+<!--
+RULE TEMPLATE - Distributed via /scaffold-rules
+Variables: {{#if agent:claude}}
+-->
+
+# Testing
+
+Use Bun's built-in test runner for unit and integration tests.
+
+## Test Types
+
+### Unit/Integration Tests (`*.spec.ts`)
+
+Standard Bun tests using `*.spec.ts` extension:
+- Run with `bun test` command
+- Used for testing business logic, utilities, and non-visual functionality
+
+## Running Tests
+
+```bash
+# Run all unit tests
+bun test
+
+# Run a specific spec test file
+bun test path/to/file.spec.ts
+
+# 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
+
+## 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

package/.claude/settings.local.json

@@ -0,0 +1,47 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bun test:*)",
+      "Bash(bun run check:*)",
+      "Bash(bun run check:write:*)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(gh repo view:*)",
+      "Bash(gh api:*)",
+      "Bash(gh repo edit:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(gh pr create:*)",
+      "Bash(git add:*)",
+      "Bash(gh run view:*)",
+      "Bash(bunx biome check:*)",
+      "Bash(git checkout:*)",
+      "mcp__agent-skills-spec__SearchAgentSkills",
+      "Bash(bunx lint-staged:*)",
+      "Bash(git revert:*)",
+      "Bash(bun biome check:*)",
+      "Bash(bun scripts/fast-find.ts:*)",
+      "mcp__bun-docs__SearchBun",
+      "Bash(bun scripts/scan-imports.ts:*)",
+      "Bash(bun:*)",
+      "Bash(ls:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(grep:*)",
+      "Bash(echo:*)",
+      "WebSearch",
+      "Bash(gh pr comment:*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:aiengineerguide.com)",
+      "Bash(DEBUG_SCAFFOLD=1 bun bin/cli.ts:*)",
+      "WebFetch(domain:cursor.com)",
+      "WebFetch(domain:docs.factory.ai)",
+      "WebFetch(domain:agents.md)",
+      "Bash(git cherry-pick:*)"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "agent-skills-spec"
+  ],
+  "outputStyle": "Learning"
+}