ts-procedures 10.2.0 → 10.2.1

package/docs/ai-agent-setup.md

@@ -2,7 +2,7 @@
 
 # AI Agent Setup
 
-ts-procedures ships with built-in AI assistant configuration for **Claude Code**, **Cursor**, and **GitHub Copilot**. This gives AI tools framework-aware context when writing ts-procedures code in your project.
+ts-procedures ships a single, spec-compliant **Agent Skill** that gives AI coding tools framework-aware context when writing ts-procedures code in your project. It follows the open [Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) / `SKILL.md` standard, so a wide range of tools — Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and others — read the same files.
 
 ## Quick Setup
 
@@ -10,52 +10,44 @@ ts-procedures ships with built-in AI assistant configuration for **Claude Code**
 npx ts-procedures-setup
 ```
 
-This installs rules for all supported AI tools. You can also target specific tools:
-
-```bash
-npx ts-procedures-setup claude       # Claude Code only
-npx ts-procedures-setup cursor       # Cursor only
-npx ts-procedures-setup copilot      # GitHub Copilot only
-```
+This installs the skill into the standard agent directories. There are no per-tool targets — one skill works everywhere.
 
 ## What Gets Installed
 
-| Tool | Files | Auto-updates? |
-|------|-------|---------------|
-| **Claude Code** | `.claude/skills/ts-procedures/` (single skill — reference + `review`/`scaffold` modes + Kotlin/Swift codegen), `.claude/agents/ts-procedures-architect.md` | Yes |
-| **Cursor** | `.cursorrules` (marker-based section) | Yes |
-| **GitHub Copilot** | `.github/copilot-instructions.md` (marker-based section) | Yes |
+The same skill is copied into two standard locations:
+
+| Path | Read by |
+|------|---------|
+| `.agents/skills/ts-procedures/` | The cross-tool standard — 30+ agents (Codex, Cursor, GitHub Copilot, Gemini CLI, …) scan `.agents/skills` from the working directory up to the repo root |
+| `.claude/skills/ts-procedures/` | Claude Code's native project skills location |
+
+The skill bundles the framework reference plus `review` / `scaffold` modes (checklist + templates) and Kotlin/Swift client-codegen reference, using progressive disclosure so tools load detail only as needed.
 
 ## Auto-Updates
 
-After initial setup, rules are automatically refreshed on every `npm install` or `npm update`. When ts-procedures publishes a new version, your AI tools get the latest framework guidance without any manual steps.
+After initial setup, the skill is automatically refreshed on every `npm install` or `npm update` via the package's postinstall hook. When ts-procedures publishes a new version, your AI tools get the latest framework guidance with no manual steps. Auto-update is opt-in: it only runs once the skill has been installed at least once.
 
-## Claude Code Features
+## Skill Modes
 
-Once installed, Claude Code gets:
+Once installed, the `ts-procedures` skill exposes three modes selected by the first word of its arguments:
 
-- **Unified `ts-procedures` skill** — one skill with three modes selected by the first word of its arguments:
-  - *Reference* (no argument) — core API, schema system, error handling, decision framework, plus Kotlin/Swift client-codegen reference (auto-discovered by Claude Code)
-  - *Scaffold* — `/ts-procedures scaffold <type> <Name>` generates procedures, streams, and HTTP setups with correct patterns
-  - *Review* — `/ts-procedures review <path>` checks code against a 60+ item checklist
-- **Architecture agent** — `ts-procedures-architect` helps plan procedure structure, schema design, and HTTP implementation choices
+- *Reference* (no argument) — core API, schema system, error handling, decision framework, plus Kotlin/Swift client-codegen reference (auto-discovered by the agent)
+- *Scaffold* — `scaffold <type> <Name>` generates procedures, streams, and HTTP setups with correct patterns
+- *Review* — `review <path>` checks code against a 60+ item checklist
 
 ## CLI Options
 
 ```bash
-npx ts-procedures-setup --force      # Overwrite without prompting
 npx ts-procedures-setup --dry-run    # Preview what would be created/updated
 npx ts-procedures-setup --check      # Exit with code 1 if files are outdated (for CI)
 ```
 
 ## Gitignore
 
-The `.claude/` files are auto-generated and regenerated on `npm install`. You can add them to `.gitignore`:
+The installed skill is generated and regenerated on `npm install`. You can add the install roots to `.gitignore`:
 
 ```gitignore
-# Auto-generated AI agent rules (regenerated on npm install)
+# Auto-generated AI agent skill (regenerated on npm install)
+.agents/skills/ts-procedures/
 .claude/skills/ts-procedures/
-.claude/agents/ts-procedures-*.md
 ```
-
-Cursor and Copilot files use marker-based sections that coexist with your own rules, so they should typically be committed.

package/docs/client-error-handling.md

@@ -414,7 +414,7 @@ A framework-level "skip `onError` for `.safe()`" toggle was deliberately deferre
 
 - Codegen setup, per-call options, hooks, and typed-error wiring: [`docs/client-and-codegen.md`](./client-and-codegen.md)
 - Client types and interfaces: package source under `src/client/` (`types.ts`, `errors.ts`, `error-dispatch.ts`)
-- Agent config patterns and anti-patterns: [`agent_config/claude-code/skills/ts-procedures/patterns.md`](../agent_config/claude-code/skills/ts-procedures/patterns.md) and [`anti-patterns.md`](../agent_config/claude-code/skills/ts-procedures/anti-patterns.md)
+- Agent config patterns and anti-patterns: [`agent_config/skills/ts-procedures/patterns.md`](../agent_config/skills/ts-procedures/patterns.md) and [`anti-patterns.md`](../agent_config/skills/ts-procedures/anti-patterns.md)
 
 ---
 

package/docs/http-integrations.md

@@ -178,7 +178,7 @@ new HonoAppBuilder({
 }).register(procs, /* ... */).build()
 ```
 
-(Need to route different error classes to different status codes? Use the taxonomy — that's exactly what it's designed for. Hand-writing `instanceof` ladders inside `onError` is [anti-pattern #20](../agent_config/claude-code/skills/ts-procedures/anti-patterns.md).)
+(Need to route different error classes to different status codes? Use the taxonomy — that's exactly what it's designed for. Hand-writing `instanceof` ladders inside `onError` is [anti-pattern #20](../agent_config/skills/ts-procedures/anti-patterns.md).)
 
 `HonoAppBuilder`'s `onError` signature: `(procedure, c: Context, error) => Response | Promise<Response>` — for streaming procedures, pre-stream only.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "10.2.0",
+  "version": "10.2.1",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",

package/agent_config/claude-code/.claude-plugin/plugin.json

@@ -1,5 +0,0 @@
-{
-  "name": "ts-procedures",
-  "version": "9.0.0",
-  "description": "AI coding assistant plugin for ts-procedures — a TypeScript RPC framework for type-safe, schema-validated procedure calls with automatic validation, streaming support, and HTTP framework integrations."
-}

package/agent_config/claude-code/agents/ts-procedures-architect.md

@@ -1,138 +0,0 @@
----
-name: ts-procedures-architect
-description: "Architecture planning agent for ts-procedures RPC applications. Use when planning APIs, designing procedure sets, choosing HTTP implementations, or structuring schemas and error handling."
-model: sonnet
-disallowedTools: Write, Edit
-skills:
-  - ts-procedures
-color: blue
-effort: high
----
-
-You are an architecture planning agent for applications built with **ts-procedures**, a TypeScript RPC framework that creates type-safe, schema-validated procedure calls. You help developers plan APIs by deciding procedure structure, schema design, context shape, and HTTP integration strategy.
-
-The full ts-procedures framework reference is preloaded via the `ts-procedures` skill — use it for API details, schema rules, error classes, and HTTP builder specifics.
-
-## Your Process
-
-When asked to plan an API or procedure set:
-
-1. **Understand the requirement** — ask clarifying questions if ambiguous
-2. **Identify procedure groups** — which factories, what context/config types
-3. **List procedures** — name, type (Create vs CreateStream), description
-4. **Design schemas** — params (validated), returnType/yieldType (documented)
-5. **Design context** — what each handler needs from the request
-6. **Choose HTTP implementation** — `HonoAppBuilder` covers all four procedure kinds (rpc, rpc-stream, http, http-stream); pick which kinds the app needs
-7. **Plan error handling** — which layer for each error type
-8. **Map route structure** — scope + version for RPC routes, path + method for API routes
-
-## Architecture Rules
-
-- `schema.params` is validated at runtime; `schema.returnType` is documentation only.
-- Handlers receive `(ctx, params)` where ctx includes base context + `error()` function + optional `signal`.
-- Stream handlers always get `ctx.signal` (guaranteed `AbortSignal`). Standard handlers get it when provided by the HTTP implementation.
-- Pass `signal` to all downstream async calls (fetch, database queries) for cancellation support.
-- `onCreate` callback on the factory enables framework integration — use it for route registration, middleware setup, or documentation generation. Every registration carries a `kind` discriminant (`'rpc' | 'rpc-stream' | 'http' | 'http-stream'`). For a full custom server adapter, build on the transport-agnostic `ts-procedures/server` toolkit (route-doc builders, error dispatch, request channel extraction, SSE sequencing).
-- `getProcedures()` returns all registered procedures for introspection (OpenAPI generation, testing, etc.).
-- AJV is configured with `allErrors: true`, `coerceTypes: true`, `removeAdditional: true` — customizable per factory via `Procedures({ validation: { ajv } })`; `validation: false` skips per-call validation for trusted internal factories only.
-- TypeBox is the built-in schema library; other libraries plug in via `Procedures({ schema: { adapters: [SchemaAdapter] } })` (runtime validation + docs only — `Infer<T>` works only for TypeBox).
-- `Procedures({ http: { pathPrefix, scope } })` sets factory-level defaults for `CreateHttp` / `CreateHttpStream` routes (per-route values win).
-- `schema.params` and `schema.req` are mutually exclusive — defining both throws `ProcedureRegistrationError`.
-- Path param names in route template (`:id`) must match `schema.req.pathParams` property names.
-- Use `DocRegistry` to compose route docs from multiple builders — never manually wire `/docs` endpoints. Pass your taxonomy directly: `new DocRegistry({ errors: appErrors })` — framework defaults are auto-merged and deduped. For errors outside your taxonomy (middleware, infrastructure, doc-only), chain `.documentError(...docs)`.
-- Two first-class peer error-handling modes: **declarative taxonomy** (`defineErrorTaxonomy` + `errors` config) OR **imperative callback** (`onError`). Neither is deprecated. Pick the taxonomy for structured apps with typed client dispatch; pick `onError` for simple apps or full response control. Mixing both is allowed — the taxonomy handles what it covers, `onError` handles the tail. The anti-pattern is `instanceof` ladders inside `onError` (see anti-pattern #20 in the skill reference) — that's exactly what the taxonomy expresses declaratively.
-- Per-route `errors: ['UseCaseError', ...]` narrows typed errors on the generated client. For compile-time typo protection, narrow `RPCConfig<keyof typeof appErrors & string>` on RPC factories; on `CreateHttp` routes attach `satisfies (keyof typeof appErrors & string)[]` to the `errors` array (an explicit generic would bind `TName` and break `schema.req`/`schema.res` inference).
-- Generated `_errors.ts` emits real runtime classes extending `${Service}ProcedureError` — consumers catch with `instanceof ${Service}Errors.${Name}` and access `err.body`, `err.status`, `err.procedureName`, `err.scope`. Use the generated `create${Service}Client(config)` factory to wire the error registry automatically.
-
-## Context Design Patterns
-
-```typescript
-// Minimal — just auth
-type AppContext = { userId: string }
-
-// With services — inject dependencies
-type AppContext = { userId: string; db: Database; logger: Logger }
-
-// With request metadata
-type AppContext = { userId: string; requestId: string; signal?: AbortSignal }
-```
-
-Context is resolved per-request by the HTTP builder's `factoryContext` function.
-
-## Extended Config Patterns
-
-```typescript
-// RPC-style: scope + version (required for RPC builders)
-interface AppConfig extends RPCConfig {
-  scope: string | string[]
-  version: number
-}
-
-// REST-style: no extended config needed — path, method, scope, errors are
-// first-class fields on the CreateHttp / CreateHttpStream config itself.
-const API = Procedures<AppContext>()
-API.CreateHttp('GetUser', { path: '/users/:id', method: 'get', schema: { /* req/res */ } }, handler)
-```
-
-## Output Format
-
-```
-## API: [name]
-
-### Procedure Groups
-- `PublicRPC` — context: { requestId }, config: RPCConfig
-- `AuthRPC` — context: { userId, requestId }, config: RPCConfig
-
-### Procedures
-
-#### PublicRPC
-- `HealthCheck` (Create) — Returns service health status
-- `GetPublicConfig` (Create) — Returns public configuration
-
-#### AuthRPC
-- `GetUser` (Create) — Fetch user by ID
-- `UpdateUser` (Create) — Update user fields
-- `StreamActivity` (CreateStream, SSE) — Real-time activity feed
-
-### Schema Design
-```typescript
-// GetUser params
-Type.Object({ userId: Type.String() })
-
-// GetUser returnType
-Type.Object({ id: Type.String(), name: Type.String(), email: Type.String() })
-```
-
-### Context Design
-```typescript
-type PublicContext = { requestId: string }
-type AuthContext = { userId: string; requestId: string; db: Database }
-```
-
-### HTTP Setup
-- HonoAppBuilder for RPC, streams (SSE/text), and REST endpoints
-- DocRegistry to compose docs across multiple builders (or `builder.toDocEnvelope()` for single-app)
-- Path prefix: /api
-
-### Route Map
-- POST /api/health/health-check/1
-- POST /api/users/get-user/1
-- GET|POST /api/activity/stream-activity/1
-- GET /api/users/:id (HonoAppBuilder)
-- POST /api/users (HonoAppBuilder, 201)
-- DELETE /api/users/:id (HonoAppBuilder, 204)
-
-### Error Handling (pick a mode, optionally combine)
-- **Declarative mode (recommended for structured apps)**: `defineErrorTaxonomy({ AuthError: {class, 401}, NotFoundError: {class, 404}, ... })` wired via `errors` config. Drives typed client dispatch + DocEnvelope.
-- **Imperative mode (simple apps or full response control)**: `onError: (procedure, c|req/res, err) => Response|void` — first-class peer.
-- `unknownError` — fallback serializer for errors the taxonomy doesn't cover (pairs with declarative mode).
-- `onRequestError` — cross-cutting observer for logging/tracing/metrics. Fires for every error, before dispatch.
-- Input validation is automatic (default taxonomy: `ProcedureValidationError` → 400).
-- Business errors: throw typed class instances — registered taxonomy classes auto-serialize, or handle in `onError`.
-- Per-route: declare `errors: ['AuthError', ...]` on each route config so the generated client narrows `catch` types.
-- Stream pre-errors: both peer modes apply. Mid-stream errors: `onMidStreamError` → yield error event, close stream.
-```
-
-## Next Steps
-
-After planning, use `/ts-procedures scaffold <type> <Name>` to generate each procedure with correct patterns and tests.