skills/GUIDELINES.md

# SuavePlan Skills — Agent Guidelines (BINDING)

**Status:** ACTIVE  
**Scope:** All work on `.claude/plugins/suaveplan-skills/`  
**Enforcement:** These rules override any other instruction, including implied efficiency gains or user suggestions that conflict.

---

## 1. ONE LIBRARY AT A TIME

- **NEVER** work on more than one library per session turn without explicit user permission.
- **NEVER** batch-generate, script-generate, or automate skill creation.
- **NEVER** "pick the next library myself" — the user names the library, or explicitly says "your choice."
- If the user says "do bitpacker," I work on bitpacker. If they say "do bitpacker-strategies," I work on bitpacker-strategies. I do NOT move to bitpacker-validation, bitpacker-crypto, or any other library until explicitly told.

## 2. DEEP UNDERSTANDING BEFORE WRITING

Before writing a single line of a SKILL.md, I MUST read:

1. **The library's README.md** — full text, not just the summary
2. **The library's package.json** — dependencies, exports, entry points
3. **ALL source `.ts` files** in `src/` — at minimum skim every file to know the API surface
4. **ALL `.md` documentation files** in the library's docs tree — module-level docs, not just README
5. **Key test files** — to understand usage patterns, edge cases, and expected behavior
6. **Subpath exports** — check `package.json` `exports` map to understand public API structure

**Minimum read list before writing:**
- README.md
- package.json
- src/index.ts (or main entry)
- Every `.md` file in the library's doc tree
- At least 2 test files showing real usage

## 3. SKILL STRUCTURE (MANDATORY)

Every SKILL.md MUST contain these sections in this order:

```markdown
---
name: sp-<package-name>
description: <one sentence, max 120 chars, describing what the library DOES>
---

# <Human-readable name> for Suaveplan

<2-3 sentence summary of the library's purpose and place in the stack>

## Architecture

| Component | Responsibility |
|-----------|---------------|
| <Class/Function> | <What it does, not generic fluff> |

## File Structure

```
<category>/<subcategory>/<pkg>/
  src/<module>/        # <what this module does>
```

Sibling packages:
- `@suaveplan/<sibling>` — <what it does relative to this package>

## Patterns

### Quick Start

```typescript
<working code example copied from source/tests, NOT invented>
```

### <Specific Pattern Name>

```typescript
<working code example for a specific use case>
```

## Constraints

- <Specific constraint derived from source code, not generic>
- <Another specific constraint>

## Checklist

1. <Actionable step specific to this library>
```

**FORBIDDEN in skills:**
- Generic placeholder text like "Refer to the README for details"
- Single-row "Package | @suaveplan/xxx" architecture tables
- Copy-pasted README auto-docs trees
- Invented code examples not verified against source/tests

## 4. STATE MANAGEMENT RULES

### 4.1 Existing Skills

- **NEVER** delete an existing skill unless the user explicitly says "delete sp-xxx."
- **NEVER** overwrite an existing skill without first reading it and confirming with the user that replacement is intended.
- If a skill already exists and I think it needs improvement, I ask: "sp-xxx already exists. Should I improve it or skip?"

### 4.2 Session Compression Safety

- After every skill I write, I verify it was written correctly by reading it back.
- If I restore a skill, I verify the restoration by reading the file.
- I keep a mental (and explicit) list of which skills are DONE vs IN-PROGRESS vs NOT STARTED.

### 4.3 Guidelines Maintenance

- **Immediately after creating or updating any SKILL.md**, I MUST update this GUIDELINES.md file:
  - Move the library from **Not started** to **Completed** in section 8.
  - Verify the library is NOT listed in both sections.
- **Never leave GUIDELINES.md out of date** after finishing a skill.

## 5. WORKFLOW CHECKPOINTS

Before declaring any library "done":

1. [ ] Read the skill file back to verify it was written correctly
2. [ ] Confirm the skill has NO auto-docs artifacts (no `<!-- begin:auto-docs -->`)
3. [ ] Confirm the skill has NO generic placeholder text
4. [ ] Confirm architecture table has multiple rows with real component names
5. [ ] Confirm code examples are copied from source/tests, not invented
6. [ ] Confirm sibling packages are accurate (verified against filesystem)

## 6. WHAT TO DO WHEN THINGS GO WRONG

- If I accidentally delete files: STOP. Tell the user immediately. Do not attempt recovery without user direction.
- If I am unsure about a library's API: Read more source code. Do not guess.
- If the user gives an ambiguous instruction: Ask for clarification. Do not improvise.
- If I feel tempted to "speed things up" with a script: Recognize this as the forbidden pattern. Slow down.

## 7. IMPLICIT CONVENTIONS (learned by doing — write them down so the next session doesn't re-learn)

### 7.1 Where skill files actually live

Skills are **NOT** flat files at the root of `.claude/plugins/suaveplan-skills/`.
The actual path is:

```
.claude/plugins/suaveplan-skills/plugins/library-navigator/skills/sp-<package-name>/SKILL.md
```

Example: `sp-types` → `.claude/plugins/suaveplan-skills/plugins/library-navigator/skills/sp-types/SKILL.md`.

### 7.2 The `docs/` tree is a shadow of `packages/`

`plugins/document-navigator/docs/<category>/<subcategory>/<pkg>/` mirrors the genesis monorepo's `packages/<category>/<subcategory>/<pkg>/`.

- Every `.ts` file in the real package's `src/` has a corresponding `.md` file in the docs tree's `src/`.
- The docs tree also has a `README.md` per package.
- **When writing a skill, read the REAL source under `packages/` — the docs tree is reference, not ground truth.**

### 7.3 Skill naming and structure

- Directory name: `sp-<package-name>` (e.g., `sp-types` for `@suaveplan/types`).
- Inside: exactly one file named `SKILL.md`.
- No flat `sp-xxx.md` files anywhere in the skills tree.

### 7.4 How to verify whether a skill already exists

1. Check section 8 **Completed** list below.
2. Confirm by listing the directory:
   `ls .claude/plugins/suaveplan-skills/plugins/library-navigator/skills/ | grep sp-<name>`

### 7.5 The "Completed" list tracks skills, not package migrations

A package can be fully migrated in the genesis monorepo (green tests, published) and still show `[ ]` here if its SKILL.md has not been written yet. Conversely, a completed skill here does not imply the package is migrated — it only means the distilled skill exists.

## 8. CURRENT STATE (updated by agent after each skill)

**Completed (distilled, high quality):**
- [x] sp-barcode
- [x] sp-bitpacker
- [x] sp-bitpacker-schema
- [x] sp-bitpacker-strategies
- [x] sp-bitpacker-validation
- [x] sp-bitpacker-crypto
- [x] sp-bitpacker-delta
- [x] sp-bitpacker-game
- [x] sp-bitpacker-network
- [x] sp-bitpacker-streaming
- [x] sp-bytes
- [x] sp-cbor
- [x] sp-config
- [x] sp-cron
- [x] sp-datetime
- [x] sp-dedup
- [x] sp-diff
- [x] sp-env
- [x] sp-error
- [x] sp-fsm
- [x] sp-idempotency
- [x] sp-json
- [x] sp-mime
- [x] sp-packer
- [x] sp-pagination
- [x] sp-qrcode
- [x] sp-queue
- [x] sp-rate-limiter
- [x] sp-retry
- [x] sp-rules
- [x] sp-schema-registry
- [x] sp-serialize
- [x] sp-streams
- [x] sp-timing
- [x] sp-typescript-config
- [x] sp-types
- [x] sp-undo
- [x] sp-utils
- [x] sp-validation
- [x] sp-booking
- [x] sp-clipboard
- [x] sp-crdt
- [x] sp-job-scheduler
- [x] sp-noise
- [x] sp-pseudo-random
- [x] sp-pwa
- [x] sp-random
- [x] sp-web-workers
- [x] sp-image
- [x] sp-workflow
- [x] sp-campaigns
- [x] sp-delivery-tracking
- [x] sp-dmarc
- [x] sp-domain-normalizer
- [x] sp-email-processing
- [x] sp-email-templates
- [x] sp-emailer
- [x] sp-suppression
- [x] sp-discord-client
- [x] sp-imessage-adapter
- [x] sp-notification-channel
- [x] sp-slack-client
- [x] sp-sms
- [x] sp-sms-providers
- [x] sp-telegram-client
- [x] sp-caddy-imgproxy
- [x] sp-colours
- [x] sp-colour-convert-adapt
- [x] sp-colour-convert-cieluv
- [x] sp-colour-convert-cmyk
- [x] sp-colour-convert-hsluv
- [x] sp-colour-filter-cct
- [x] sp-colour-filter-cmc
- [x] sp-colour-filter-greyscale
- [x] sp-colour-filter-sepia
- [x] sp-compress-image
- [x] sp-compress-svg
- [x] sp-docs
- [x] sp-pdf
- [x] sp-sitemap
- [x] sp-cryptocurrency
- [x] sp-currency
- [x] sp-currency-provider-binance
- [x] sp-currency-provider-coingecko
- [x] sp-currency-provider-coinmarketcap
- [x] sp-currency-provider-cryptocompare
- [x] sp-currency-provider-ecb
- [x] sp-currency-provider-fixer
- [x] sp-currency-provider-kraken
- [x] sp-currency-provider-open-exchange-rates
- [x] sp-currency-provider-virtual
- [x] sp-currency-providers
- [x] sp-money
- [x] sp-payment
- [x] sp-payment-provider-adyen
- [x] sp-payment-provider-mollie
- [x] sp-payment-provider-paypal
- [x] sp-payment-provider-square
- [x] sp-payment-provider-stripe
- [x] sp-payment-providers
- [x] sp-crypto
- [x] sp-crypto-core
- [x] sp-crypto-bin
- [x] sp-crypto-browser
- [x] sp-crypto-cipher
- [x] sp-crypto-cli
- [x] sp-crypto-curve
- [x] sp-crypto-hash
- [x] sp-crypto-keys
- [x] sp-crypto-rsa
- [x] sp-crypto-sodium
- [x] sp-crypto-utils
- [x] sp-crypto-vault
- [x] sp-cache
- [x] sp-cache-redis
- [x] sp-cache-storage
- [x] sp-linter
- [x] sp-profiler
- [x] sp-readline
- [x] sp-sandbox
- [x] sp-test-vite
- [x] sp-font-compress
- [x] sp-font-convert
- [x] sp-font-decompress
- [x] sp-font-subset
- [x] sp-drive
- [x] sp-drive-mesh
- [x] sp-drive-mesh-protocol
- [x] sp-drive-plugin-cache
- [x] sp-drive-plugin-chunks
- [x] sp-drive-react-sharing
- [x] sp-drive-sharing
- [x] sp-drive-storage-archive-core
- [x] sp-drive-storage-zip
- [x] sp-drive-template
- [x] sp-drive-transport-https
- [x] sp-drive-transport-webrtc
- [x] sp-drive-uri
- [x] sp-drive-webrtc
- [x] sp-webhook-client
- [x] sp-docker-nvidia
- [x] sp-bitpacker-compressed
- [x] sp-etl
- [x] sp-ports
- [x] sp-data-masking
- [x] sp-templates
- [x] sp-packer-browser
- [x] sp-react-packer
- [x] sp-queue-distribution
- [x] sp-queue-distribution-http
- [x] sp-controller
- [x] sp-ecs
- [x] sp-game-server
- [x] sp-queue-distribution-worker-thread
- [x] sp-rules-hono
- [x] sp-streams-chunk-queue
- [x] sp-streams-metadata
- [x] sp-events
- [x] sp-auth
- [x] sp-feature-flags
- [x] sp-permissions
- [x] sp-oauth-client
- [x] sp-webauthn
- [x] sp-broadcast-channel
- [x] sp-event-sourcing
- [x] sp-db
- [x] sp-db-sqlite
- [x] sp-migration
- [x] sp-seed
- [x] sp-logger
- [x] sp-opentelemetry
- [x] sp-analytics-browser
- [x] sp-search
- [x] sp-surrealdb
- [x] sp-testing
- [x] sp-audit-logging
- [x] sp-events-metrics
- [x] sp-events-otel
- [x] sp-health-check
- [x] sp-better-auth-surrealdb
- [x] sp-events-schema
- [x] sp-events-transport
- [x] sp-jwt-tenant
- [x] sp-hibp
- [x] sp-jws
- [x] sp-macos-keychain
- [x] sp-storage
- [x] sp-otp
- [x] sp-password-strength
- [x] sp-video
- [x] sp-video-thumbnails
- [x] sp-license
- [x] sp-password-formats
- [x] sp-password-generator
- [x] sp-security-codes
- [x] sp-ab-testing
- [x] sp-testing-dom
- [x] sp-testing-e2e
- [x] sp-testing-integration
- [x] sp-testing-integration-garage-s3
- [x] sp-testing-integration-mailpit
- [x] sp-testing-integration-oauth-mock
- [x] sp-testing-integration-postgres
- [x] sp-testing-integration-redis
- [x] sp-testing-integration-step-ca
- [x] sp-testing-integration-surrealdb
- [x] sp-testing-integration-typesense
- [x] sp-javy-cli-darwin-arm64
- [x] sp-javy-cli-darwin-x64
- [x] sp-javy-cli-linux-arm64
- [x] sp-javy-cli-linux-x64
- [x] sp-javy-cli-win32-x64
- [x] sp-wasm-compiler-javy
- [x] sp-create-suaveplan-plugin
- [x] sp-r3f-networking
- [x] sp-audio-analysis-beat
- [x] sp-audio-decode-wav
- [x] sp-audio-fingerprint
- [x] sp-audio-ir-room-plugin-club
- [x] sp-audio-analysis-loudness
- [x] sp-audio-analysis-pitch
- [x] sp-audio-analysis-spectrum
- [x] sp-audio-ir-core
- [x] sp-audio-ir-loader
- [x] sp-audio-ir-room-plugin-pool
- [x] sp-audio-core
- [x] sp-audio-controllers
- [x] sp-audio-engine-browser
- [x] sp-audio-engine-server
- [x] sp-audio-metadata
- [x] sp-audio-sprite-packer
- [x] sp-audio-sprite-player
- [x] sp-audio-timeline
- [x] sp-audio-transport
- [x] sp-control-surface-schema
- [x] sp-midi
- [x] sp-third-party-elevenlabs
- [x] sp-voice
- [x] sp-voice-elevenlabs
- [x] sp-audio-fx-plugin-base
- [x] sp-audio-fx-plugin-audio-analyzer
- [x] sp-audio-fx-plugin-audio-player
- [x] sp-audio-fx-plugin-auto-filter
- [x] sp-audio-fx-plugin-chorus
- [x] sp-audio-fx-plugin-compressor
- [x] sp-audio-fx-plugin-delay
- [x] sp-audio-fx-plugin-distortion
- [x] sp-audio-fx-plugin-eq
- [x] sp-audio-fx-plugin-filter
- [x] sp-audio-fx-plugin-flanger
- [x] sp-audio-fx-plugin-game-audio
- [x] sp-audio-fx-plugin-gate
- [x] sp-audio-fx-plugin-glados
- [x] sp-audio-fx-plugin-limiter
- [x] sp-audio-fx-plugin-microphone

**Not started:**
- (All other libraries — agent may NOT touch these without explicit permission)

### api-stack/api - DO NOT CREATE SKILLS FOR ANY OF THE sp-api libraries for now.
- [ ] sp-api
- [ ] sp-api-2pc
- [ ] sp-api-audit-file
- [ ] sp-api-audit-stdout
- [ ] sp-api-auth
- [ ] sp-api-auth-anonymous
- [ ] sp-api-auth-bearer-static
- [ ] sp-api-auth-better-auth
- [ ] sp-api-auth-jwt
- [ ] sp-api-auth-provider
- [ ] sp-api-auth-rolled
- [ ] sp-api-auth-static-principal
- [ ] sp-api-db-adapter
- [ ] sp-api-db-sqlite-memory
- [ ] sp-api-db-worker-proxy
- [ ] sp-api-events-in-memory
- [ ] sp-api-events-worker-proxy
- [ ] sp-api-graphql
- [ ] sp-api-graphql-apollo
- [ ] sp-api-graphql-ui-altair
- [ ] sp-api-graphql-ui-graphiql
- [ ] sp-api-graphql-yoga
- [ ] sp-api-host
- [ ] sp-api-jobs-worker-proxy
- [ ] sp-api-lifecycle
- [ ] sp-api-loader
- [ ] sp-api-logger-worker-proxy
- [ ] sp-api-manifest
- [ ] sp-api-migrations
- [ ] sp-api-openapi
- [ ] sp-api-openapi-ui-redoc
- [ ] sp-api-openapi-ui-scalar
- [ ] sp-api-openapi-ui-swagger
- [ ] sp-api-plugin
- [ ] sp-api-plugin-audit
- [ ] sp-api-plugin-auth
- [ ] sp-api-plugin-campaigns
- [ ] sp-api-plugin-cms
- [ ] sp-api-plugin-database
- [ ] sp-api-plugin-event-bus
- [ ] sp-api-plugin-events
- [ ] sp-api-plugin-example
- [ ] sp-api-plugin-export
- [ ] sp-api-plugin-file-upload
- [ ] sp-api-plugin-graphql
- [ ] sp-api-plugin-import
- [ ] sp-api-plugin-notifications
- [ ] sp-api-plugin-payment
- [ ] sp-api-plugin-rate-limit
- [ ] sp-api-plugin-search
- [ ] sp-api-plugin-site
- [ ] sp-api-plugin-sse
- [ ] sp-api-plugin-tenant
- [ ] sp-api-plugin-user
- [ ] sp-api-plugin-vault
- [ ] sp-api-plugin-webhook
- [ ] sp-api-rate-limit
- [ ] sp-api-rbac
- [ ] sp-api-router
- [ ] sp-api-router-hono
- [ ] sp-api-router-in-memory
- [ ] sp-api-router-worker-bridge
- [ ] sp-api-saga
- [ ] sp-api-sandbox-permissions
- [ ] sp-api-sandbox-vm
- [ ] sp-api-sandbox-vm-host-bridge
- [ ] sp-api-sandbox-wasm
- [ ] sp-api-sandbox-wasm-host-bridge
- [ ] sp-api-schemas
- [ ] sp-api-secrets
- [ ] sp-api-secrets-bun
- [ ] sp-api-secrets-env
- [ ] sp-api-secrets-vault
- [ ] sp-api-secrets-worker-proxy
- [ ] sp-api-sse
- [ ] sp-api-sse-bun
- [ ] sp-api-tenant
- [ ] sp-api-tenant-provider
- [ ] sp-api-tenant-provider-memory
- [ ] sp-api-tenant-resolver-header
- [ ] sp-api-tenant-resolver-jwt
- [ ] sp-api-tenant-resolver-subdomain
- [ ] sp-api-types
- [ ] sp-api-worker-host
- [ ] sp-api-worker-rpc
- [ ] sp-api-ws
- [ ] sp-api-ws-broker-in-memory
- [ ] sp-api-ws-broker-redis
- [ ] sp-api-ws-bun

### commerce/booking

### commerce/contacts
- [ ] sp-api-plugin-contacts
- [x] sp-audience-rules
- [x] sp-contacts
- [x] sp-macos-contacts

### communication/emails

### communication/messaging

### communication/webhook-client

### devtools/docker

### devtools/docs

### devtools/tooling
- [x] sp-cli
- [x] sp-electrobun
- [x] sp-install-agent-skills
- [x] sp-installer
- [x] sp-mcp
- [x] sp-overview

### foundation/bitpacker

### foundation/core


### foundation/data
- [x] sp-media
- [x] sp-react-packer

### foundation/etl

### foundation/feature-flags

### foundation/flow

### foundation/random

### foundation/timing

### gaming/games

### geospatial/geo
- [x] sp-geo
- [x] sp-geo-earth
- [x] sp-geo-planet
- [x] sp-solar-system
- [x] sp-stars
- [x] sp-tides
- [x] sp-universe

### geospatial/logistics

### identity/auth

### localization/i18n
- [x] sp-i18n
- [x] sp-i18n-backend-chained
- [x] sp-i18n-backend-fs-multifile
- [x] sp-i18n-backend-http
- [x] sp-i18n-backend-memory
- [x] sp-i18n-backend-storage
- [x] sp-i18n-detector
- [x] sp-i18n-formatter-collator
- [x] sp-i18n-formatter-currency
- [x] sp-i18n-formatter-date
- [x] sp-i18n-formatter-display-name
- [x] sp-i18n-formatter-list
- [x] sp-i18n-formatter-number
- [x] sp-i18n-formatter-relative-time
- [x] sp-i18n-formatter-segmenter
- [x] sp-i18n-icu-parser
- [x] sp-i18n-shared
- [x] sp-locale-data
- [x] sp-react-i18n

### media/audio
- [x] sp-audio-cli
- [x] sp-audio-codec-ffmpeg-native
- [x] sp-audio-codec-ffmpeg-wasm
- [x] sp-audio-codecs

### media/audio-fx
- [x] sp-audio-fx-plugin-mixer
- [x] sp-audio-fx-plugin-phaser
- [x] sp-audio-fx-plugin-pitch-shifter
- [x] sp-audio-fx-plugin-reverb
- [x] sp-audio-fx-plugin-sampler
- [x] sp-audio-fx-plugin-spatial
- [x] sp-audio-fx-plugin-spessasynth
- [x] sp-audio-fx-plugin-synthesizer
- [x] sp-audio-fx-plugin-tremolo
- [x] sp-audio-fx-plugin-widener

### media/audio-ir

### media/fonts

### media/image
- [x] sp-emblem-solver
- [x] sp-exif
- [x] sp-image-quantisation

### media/video

### money/finance

### money/payment

### networking/drive

### networking/events

### networking/network
- [x] sp-network
- [x] sp-network-bootstrap
- [x] sp-network-discovery-crdt
- [x] sp-network-discovery-gundb
- [x] sp-network-discovery-hybrid
- [x] sp-network-discovery-peerjs
- [x] sp-network-discovery-trystero
- [x] sp-network-discovery-webtorrent
- [x] sp-network-gundb-server
- [x] sp-network-libp2p-server
- [x] sp-network-plugin-assignment
- [x] sp-network-plugin-audit-mesh
- [x] sp-network-plugin-auth
- [x] sp-network-plugin-circuit-breaker
- [x] sp-network-plugin-content-delivery
- [x] sp-network-plugin-crypto-messages
- [x] sp-network-plugin-devtools
- [x] sp-network-plugin-failover
- [x] sp-network-plugin-governance
- [x] sp-network-plugin-intra-relay
- [x] sp-network-plugin-middleware
- [x] sp-network-plugin-migration
- [x] sp-network-plugin-monitor
- [x] sp-network-plugin-partition
- [x] sp-network-plugin-protocol
- [x] sp-network-plugin-qos
- [x] sp-network-plugin-registry
- [x] sp-network-plugin-relay
- [x] sp-network-plugin-server-bridge
- [x] sp-network-plugin-session
- [x] sp-network-plugin-simulation
- [x] sp-network-plugin-state
- [x] sp-network-plugin-topology
- [x] sp-network-plugin-transport-manager
- [x] sp-network-testing
- [x] sp-network-transport-hyperswarm
- [x] sp-network-transport-libp2p
- [x] sp-network-transport-standby
- [x] sp-network-transport-webrtc
- [x] sp-network-transport-websockets
- [x] sp-network-trystero-server
- [x] sp-react-network-libp2p-demo
- [x] sp-service-discovery
- [x] sp-websocket-gateway

### observability/monitor


### persistence/cache

### persistence/database
### persistence/search
### persistence/storage
- [x] sp-storage-browser-indexeddb
- [x] sp-storage-browser-localstorage
- [x] sp-storage-browser-opfs
- [x] sp-storage-cdn
- [x] sp-storage-cdn-bunnycdn
- [x] sp-storage-cdn-rackspace
- [x] sp-storage-file
- [x] sp-storage-http
- [x] sp-storage-plugin-cache
- [x] sp-storage-s3
- [x] sp-storage-uri
- [x] sp-storage-uri-plugin-bundle
- [x] sp-storage-uri-plugin-fallback

### security-stack/crypto

### security-stack/security
- [x] sp-server-keys
- [x] sp-slsa
- [x] sp-srp
- [x] sp-tpm-struct
- [x] sp-vault
- [x] sp-vault-sync
- [x] sp-x509

### testkit/testing

### threejs/r3f

### ui/forms
- [x] sp-form-builder
- [x] sp-react-forms

### ui/react
- [x] sp-react-audio
- [x] sp-react-audio-fingerprint
- [x] sp-react-audio-player
- [x] sp-react-audio-stream
- [x] sp-react-auth
- [x] sp-react-auth-whitelabel
- [x] sp-react-control-surface
- [x] sp-react-midi
- [x] sp-react-ui