ts-procedures 5.9.1 → 5.10.0

package/README.md

@@ -42,7 +42,7 @@ const user2 = await procedure({}, { userId: '456' })
 
 ## Features
 
-- **[Core Procedures](docs/core.md)** — Type-safe procedure definitions with `Procedures()`, `Create`, and `CreateStream`. Includes schema validation (Suretype / TypeBox), error handling, generics, testing patterns, and the full API reference.
+- **[Core Procedures](docs/core.md)** — Type-safe procedure definitions with `Procedures()`, `Create`, and `CreateStream`. Includes schema validation with TypeBox, error handling, generics, testing patterns, and the full API reference.
 
 - **[Streaming](docs/streaming.md)** — Async generator procedures with yield validation, abort signal integration, SSE examples, and stream error handling.
 

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

@@ -1,64 +1,46 @@
 ---
 name: ts-procedures-architect
-description: "Architecture planning agent for ts-procedures RPC applications. Decides procedure structure, schema design, context shape, HTTP implementation choice, error handling strategy, and streaming architecture. Use when planning APIs, designing procedure sets, or choosing between Express/Hono implementations."
+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:
+  - guide
+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.
 
-## Core Concepts
+The full ts-procedures framework reference is preloaded via the guide skill — use it for API details, schema rules, error classes, and HTTP builder specifics.
 
-| Concept | Role |
-|---------|------|
-| `Procedures<TContext, TExtendedConfig>(builder?)` | Factory that creates `Create` and `CreateStream` functions scoped to a shared context type |
-| `Create(name, config, handler)` | Registers a standard async procedure with optional schema validation |
-| `CreateStream(name, config, handler)` | Registers a streaming procedure (async generator) with AbortSignal support |
-| `TContext` | Base context type injected into all handlers (auth, request info, services) |
-| `TExtendedConfig` | Additional config fields on every procedure (scope, version, permissions, etc.) |
-| `schema.params` | TypeBox schema — validated at runtime via AJV |
-| `schema.input` | Structured multi-channel input — each key independently typed/validated (alternative to `schema.params`) |
-| `schema.returnType` | Documentation only — NOT validated at runtime |
-| `schema.yieldType` | Schema for each streamed value — validated only if `validateYields: true` |
-
-## Decision Framework
-
-### Which procedure type?
-
-1. Request → single response? → **Create** (standard async procedure)
-2. Request → multiple values over time? → **CreateStream** (async generator)
-3. Long-running task with progress? → **CreateStream** with progress yields
-4. Real-time data feed? → **CreateStream** with SSE mode
-
-### Which schema library?
-
-- Use **TypeBox** (`import { Type } from 'typebox'`)
-- TypeBox schemas are valid JSON Schema — they work directly with AJV
-- Define schemas with `Type.Object({ ... })`, `Type.String()`, `Type.Number()`, etc.
-- Use `Type.Optional(...)` for optional fields
-
-### Which HTTP implementation?
-
-| Implementation | Use When |
-|----------------|----------|
-| `ExpressRPCAppBuilder` | Existing Express app, need RPC endpoints alongside REST |
-| `HonoRPCAppBuilder` | Existing Hono app, edge/serverless, need RPC endpoints |
-| `HonoStreamAppBuilder` | Need streaming (SSE or text), Hono-based |
-| `HonoAPIAppBuilder` | REST-style API with per-channel input (pathParams, query, body, headers) |
-| Multiple builders | Combine RPC + streaming on the same Hono app |
+## Your Process
 
-### Stream mode?
+When asked to plan an API or procedure set:
 
-- **SSE** (`'sse'`) — Browser EventSource API, automatic reconnection, event types. Default.
-- **Text** (`'text'`) — Newline-delimited JSON. Simpler, works with any HTTP client.
+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** — Express, Hono RPC, Hono Stream, Hono API, or combination
+7. **Plan error handling** — which layer for each error type
+8. **Map route structure** — scope + version for RPC routes, path + method for API routes
 
-### schema.params vs schema.input?
+## Architecture Rules
 
-- **RPC-style** (single `params` object, POST-only) → `schema.params`
-- **REST-style** (multiple HTTP input sources) → `schema.input`
-- `schema.input` and `schema.params` are **mutually exclusive**
-- `schema.input` channels: `pathParams`, `query`, `body`, `headers`
+- `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.
+- `getProcedures()` returns all registered procedures for introspection (OpenAPI generation, testing, etc.).
+- AJV is configured with `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
+- `schema.params` and `schema.input` are mutually exclusive — defining both throws `ProcedureRegistrationError`.
+- `HonoAPIAppBuilder.build()` is async — always `await` it.
+- Path param names in route template (`:id`) must match `schema.input.pathParams` property names.
+- Use `DocRegistry` to compose route docs from multiple builders — never manually wire `/docs` endpoints.
 
-### How to structure context?
+## Context Design Patterns
 
 ```typescript
 // Minimal — just auth
@@ -73,65 +55,22 @@ type AppContext = { userId: string; requestId: string; signal?: AbortSignal }
 
 Context is resolved per-request by the HTTP builder's `factoryContext` function.
 
-### How to structure extended config?
+## Extended Config Patterns
 
 ```typescript
-// API versioning + scoping (required for HTTP builders)
+// RPC-style: scope + version (required for RPC builders)
 interface AppConfig extends RPCConfig {
-  scope: string | string[]   // URL path segments
-  version: number            // API version
+  scope: string | string[]
+  version: number
 }
 
-// With authorization
-interface AppConfig extends RPCConfig {
-  permissions?: string[]     // Required permissions
-  rateLimit?: number         // Requests per minute
+// REST-style: path + method (required for API builder)
+interface AppConfig extends APIConfig {
+  path: string
+  method: HttpMethod
 }
 ```
 
-### How to group procedures?
-
-- **By domain**: `UserProcedures`, `OrderProcedures`, `PaymentProcedures`
-- **By access level**: `PublicRPC`, `AuthenticatedRPC`, `AdminRPC`
-- **By transport**: `StandardRPC` (Create), `StreamRPC` (CreateStream)
-- Each group gets its own `Procedures<Context, Config>()` factory
-
-### Error handling strategy?
-
-| Layer | Mechanism |
-|-------|-----------|
-| Input validation | Automatic via `schema.params` — throws `ProcedureValidationError` |
-| Business logic errors | `ctx.error(message, meta?)` — throws `ProcedureError` |
-| Unexpected errors | Automatically wrapped in `ProcedureError` with stack enhancement |
-| HTTP error responses | `onError` callback in HTTP builder config |
-| Mid-stream errors | `onMidStreamError` callback in `HonoStreamAppBuilder` |
-
-## 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** — Express, Hono, or both
-7. **Plan error handling** — which layer for each error type
-8. **Map route structure** — scope + version → URL paths
-
-## 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.
-- `getProcedures()` returns all registered procedures for introspection (OpenAPI generation, testing, etc.).
-- AJV is configured with `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
-- `schema.params` and `schema.input` are mutually exclusive — defining both throws `ProcedureRegistrationError`.
-- `HonoAPIAppBuilder.build()` is async — always `await` it.
-- Path param names in route template (`:id`) must match `schema.input.pathParams` property names.
-
 ## Output Format
 
 ```
@@ -168,8 +107,10 @@ type AuthContext = { userId: string; requestId: string; db: Database }
 ```
 
 ### HTTP Setup
-- ExpressRPCAppBuilder for standard RPC
+- ExpressRPCAppBuilder or HonoRPCAppBuilder for standard RPC
 - HonoStreamAppBuilder for streaming (SSE mode)
+- HonoAPIAppBuilder for REST-style endpoints
+- DocRegistry to compose docs from all builders
 - Path prefix: /api
 
 ### Route Map
@@ -184,5 +125,9 @@ type AuthContext = { userId: string; requestId: string; db: Database }
 - Input validation: automatic (schema.params)
 - Auth failures: ctx.error('Unauthorized', { code: 401 })
 - Not found: ctx.error('User not found', { code: 404 })
-- Stream errors: onMidStreamError → yield error event, close stream
+- 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.

package/agent_config/claude-code/skills/guide/SKILL.md

@@ -1,22 +1,29 @@
 ---
 name: guide
-description: "ts-procedures framework reference — core API, schema validation, error classes, context shape, HTTP implementations, and decision framework. Auto-loaded when ts-procedures imports are detected."
-invocable_by:
-  - model
+description: "TypeScript RPC framework reference for ts-procedures — schema validation, error handling, HTTP builders, streaming, and code generation. Use when writing, reviewing, or debugging procedures, configuring HTTP builders, or designing schemas."
+user-invocable: false
 ---
 
 # ts-procedures Framework Reference
 
 You are assisting a developer using **ts-procedures**, a TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Always follow these rules when writing or reviewing code.
 
+## What Are You Trying to Do?
+
+Load the right reference for your task:
+
+- **Writing new procedures or HTTP routes?** Read [patterns.md](patterns.md) — prescribed code examples for every procedure type and HTTP integration
+- **Reviewing or debugging existing code?** Read [anti-patterns.md](anti-patterns.md) — 20 common mistakes with before/after fixes and severity ratings
+- **Need exact API signatures or type definitions?** Read [api-reference.md](api-reference.md) — complete API documentation with type signatures for every export
+
 ## Core Flow
 
 ```
 Procedures<TContext, TExtendedConfig>(builder?)
-    ↓
-Create(name, config, handler)       → Standard async procedure
-CreateStream(name, config, handler) → Streaming async generator
-    ↓
+    |
+Create(name, config, handler)       --> Standard async procedure
+CreateStream(name, config, handler) --> Streaming async generator
+    |
 Returns: { [name]: handler, procedure: handler, info: metadata }
 ```
 
@@ -48,21 +55,18 @@ Handlers receive `(ctx, params)` where ctx includes:
 | `error(message, meta?)` | `(string, object?) => ProcedureError` | Always |
 | `signal` | `AbortSignal` | **Guaranteed** in CreateStream; optional in Create (present when HTTP impl provides it) |
 
-
 ## Schema System
 
 Uses **TypeBox** for schema definitions (`import { Type } from 'typebox'`):
 
-| Library | Detection | Example |
-|---------|-----------|---------|
-| **TypeBox** | `~kind` symbol | `Type.Object({ name: Type.String() })` |
+| Schema Field | Behavior |
+|-------------|----------|
+| `schema.params` | **Validated at runtime** via AJV |
+| `schema.returnType` | **Documentation only**, never validated |
+| `schema.yieldType` | Validated only if `validateYields: true` in CreateStream config |
+| `schema.input` | Structured multi-channel input — alternative to `schema.params`, mutually exclusive |
 
-### Validation Rules
-
-- `schema.params` — **Validated at runtime** via AJV
-- `schema.returnType` — **Documentation only**, never validated
-- `schema.yieldType` — Validated only if `validateYields: true` in CreateStream config
-- AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`
+AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`
 
 ## Error Classes
 
@@ -82,15 +86,16 @@ All errors include `definedAt` (file:line:column) and enhanced stack traces poin
 | `ExpressRPCAppBuilder` | `ts-procedures/express-rpc` | POST JSON |
 | `HonoRPCAppBuilder` | `ts-procedures/hono-rpc` | POST JSON |
 | `HonoStreamAppBuilder` | `ts-procedures/hono-stream` | SSE or newline-delimited JSON |
+| `HonoAPIAppBuilder` | `ts-procedures/hono-api` | REST-style with per-channel input |
 | `DocRegistry` | `ts-procedures/http-docs` | Compose route docs from multiple builders |
 
-### Route Path Format
+### Route Path Format (RPC)
 
 ```
 {pathPrefix}/{scope}/{kebab-case-name}/{version}
 ```
 
-Example: `Create('GetUser', { scope: 'users', version: 1 }, ...)` → `POST /users/get-user/1`
+Example: `Create('GetUser', { scope: 'users', version: 1 }, ...)` --> `POST /users/get-user/1`
 
 ### Builder Pattern
 
@@ -116,28 +121,38 @@ const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
 ## Decision Framework
 
 **Which procedure type?**
-- Request → single response → **Create**
-- Request → multiple values over time → **CreateStream**
+- Request --> single response --> **Create**
+- Request --> multiple values over time --> **CreateStream**
 
-**Which schema library?**
-- Use **TypeBox** (`import { Type } from 'typebox'`)
-- TypeBox schemas are valid JSON Schema directly
-- Use `Type.Optional(...)` for optional fields
+**Which schema approach?**
+- RPC-style (single `params` object, POST-only) --> `schema.params`
+- REST-style (multiple HTTP input sources) --> `schema.input`
+- `schema.params` and `schema.input` are **mutually exclusive**
 
 **Which HTTP implementation?**
-- Express app → **ExpressRPCAppBuilder**
-- Hono app (standard RPC) → **HonoRPCAppBuilder**
-- Hono app (streaming) → **HonoStreamAppBuilder**
-- SSE with browser EventSource → `streamMode: 'sse'`
-- Simple text streaming → `streamMode: 'text'`
+- Express app --> **ExpressRPCAppBuilder**
+- Hono app (standard RPC) --> **HonoRPCAppBuilder**
+- Hono app (streaming) --> **HonoStreamAppBuilder**
+- Hono app (REST-style) --> **HonoAPIAppBuilder**
+- SSE with browser EventSource --> `streamMode: 'sse'`
+- Simple text streaming --> `streamMode: 'text'`
 
 **How to group procedures?**
 - By domain: `UserProcedures`, `OrderProcedures`
 - By access level: `PublicRPC`, `AuthenticatedRPC`
 - Each group = one `Procedures()` factory call
 
-## Supporting Files
+## Package Documentation
+
+The npm package ships user-facing documentation with narrative explanations and setup guides. Use these for deeper conceptual context beyond the prescriptive skill files above. Find them relative to the package root (e.g., `node_modules/ts-procedures/docs/`):
+
+| File | Covers |
+|------|--------|
+| `docs/core.md` | Procedures factory, Create, CreateStream, schema.input, error handling |
+| `docs/streaming.md` | Streaming procedures, AbortSignal, SSE patterns |
+| `docs/http-integrations.md` | Express RPC, Hono RPC/Stream/API builders, DocRegistry |
+| `docs/client-and-codegen.md` | Client code generation, createClient, CLI options |
+
+## Workflow
 
-For complete API details, see `api-reference.md` in this skill directory.
-For prescribed patterns with code examples, see `patterns.md`.
-For common mistakes to avoid, see `anti-patterns.md`.
+After planning with the **ts-procedures-architect** agent, use `/ts-procedures:scaffold <type> <Name>` to generate implementations. Use `/ts-procedures:review <path>` to validate existing code.

package/agent_config/claude-code/skills/guide/anti-patterns.md

@@ -634,8 +634,9 @@ const app = await new HonoAPIAppBuilder()
 | 12 | Create with HonoStreamAppBuilder | Procedures silently ignored | CRITICAL |
 | 13 | Plain JSON Schema objects instead of TypeBox | ProcedureRegistrationError | CRITICAL |
 | 14 | Wrong error handler for streams | Unhandled errors or wrong response format | WARNING |
-| 15 | Manual doc building | Fragile, incomplete documentation | SUGGESTION |
-| 16 | Unhandled async context factory | Request crashes | WARNING |
-| 17 | Both schema.params and schema.input | ProcedureRegistrationError at startup | CRITICAL |
-| 18 | Mismatched path param names | Build-time error or confusing validation failures | CRITICAL |
-| 19 | Not awaiting HonoAPIAppBuilder.build() | Using unresolved Promise as app | CRITICAL |
+| 15 | Manual doc building instead of extendProcedureDoc | Fragile, incomplete documentation | SUGGESTION |
+| 16 | Manual /docs endpoint instead of DocRegistry | Duplicated boilerplate, missing error schemas | SUGGESTION |
+| 17 | Unhandled async context factory | Request crashes | WARNING |
+| 18 | Both schema.params and schema.input | ProcedureRegistrationError at startup | CRITICAL |
+| 19 | Mismatched path param names | Build-time error or confusing validation failures | CRITICAL |
+| 20 | Not awaiting HonoAPIAppBuilder.build() | Using unresolved Promise as app | CRITICAL |

package/agent_config/claude-code/skills/guide/api-reference.md

@@ -1,54 +1,5 @@
 # ts-procedures API Reference
 
-## Imports
-
-```typescript
-// Core
-import { Procedures } from 'ts-procedures'
-import type {
-  TLocalContext,
-  TStreamContext,
-  TProcedureRegistration,
-  TStreamProcedureRegistration,
-} from 'ts-procedures'
-
-// Errors
-import {
-  ProcedureError,
-  ProcedureValidationError,
-  ProcedureYieldValidationError,
-  ProcedureRegistrationError,
-} from 'ts-procedures'
-
-// Schema utilities
-import { extractJsonSchema } from 'ts-procedures'
-import { schemaParser } from 'ts-procedures'
-import { isTypeboxSchema } from 'ts-procedures'
-import type { TSchemaLib, TSchemaLibGenerator, TJSONSchema, TSchemaParsed, TSchemaValidationError } from 'ts-procedures'
-
-// Stack utilities
-import { captureDefinitionInfo, formatDefinitionInfo } from 'ts-procedures'
-import type { DefinitionLocation, DefinitionInfo } from 'ts-procedures'
-
-// HTTP types (types only, no runtime)
-import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode, APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/http'
-
-// Express RPC
-import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
-
-// Hono RPC
-import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
-
-// Hono Streaming
-import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
-
-// Hono API (REST-style)
-import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
-import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/hono-api'
-```
-
----
-
 ## Procedures\<TContext, TExtendedConfig\>(builder?)
 
 Factory function that creates a scoped procedure registration system.
@@ -985,3 +936,63 @@ type DefinitionInfo = {
   definitionStack?: string
 }
 ```
+
+---
+
+## Imports
+
+```typescript
+// Core
+import { Procedures } from 'ts-procedures'
+import type {
+  TLocalContext,
+  TStreamContext,
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+} from 'ts-procedures'
+
+// Errors
+import {
+  ProcedureError,
+  ProcedureValidationError,
+  ProcedureYieldValidationError,
+  ProcedureRegistrationError,
+} from 'ts-procedures'
+
+// Schema utilities
+import { extractJsonSchema } from 'ts-procedures'
+import { schemaParser } from 'ts-procedures'
+import { isTypeboxSchema } from 'ts-procedures'
+import type { TSchemaLib, TSchemaLibGenerator, TJSONSchema, TSchemaParsed, TSchemaValidationError } from 'ts-procedures'
+
+// Stack utilities
+import { captureDefinitionInfo, formatDefinitionInfo } from 'ts-procedures'
+import type { DefinitionLocation, DefinitionInfo } from 'ts-procedures'
+
+// HTTP types (types only, no runtime)
+import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode, APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/http'
+
+// Express RPC
+import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
+
+// Hono RPC
+import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+
+// Hono Streaming
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+
+// Hono API (REST-style)
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from 'ts-procedures/hono-api'
+
+// Client
+import { createClient, createFetchAdapter } from 'ts-procedures/client'
+import type { ClientAdapter, ClientHooks, ClientInstance, TypedStream } from 'ts-procedures/client'
+
+// Code generation
+import { generateClient } from 'ts-procedures/codegen'
+
+// Documentation
+import { DocRegistry } from 'ts-procedures/http-docs'
+import type { DocEnvelope, DocSource, HeaderDoc, ErrorDoc } from 'ts-procedures/http-docs'
+```

package/agent_config/claude-code/skills/review/SKILL.md

@@ -1,18 +1,10 @@
 ---
 name: review
-description: "Review code for ts-procedures pattern adherence. Usage: /ts-procedures:review <path>"
-invocable_by:
-  - user
-  - model
-user_instructions: |
-  Usage: /ts-procedures:review <path>
-
-  Reviews files at the given path for ts-procedures pattern adherence.
-  Accepts a file path or directory.
-
-  Examples:
-    /ts-procedures:review src/procedures/
-    /ts-procedures:review src/procedures/GetUser.procedure.ts
+description: "Review ts-procedures code for pattern adherence, schema correctness, error handling, and signal propagation."
+argument-hint: "<path>"
+allowed-tools: Read Grep Glob
+context: fork
+effort: high
 ---
 
 # Review ts-procedures Code
@@ -22,9 +14,10 @@ Parse `$ARGUMENTS` as a file or directory path. If a directory, review all `.ts`
 ## Instructions
 
 1. Read the target file(s).
-2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/express-rpc`, `ts-procedures/hono-rpc`, `ts-procedures/hono-stream`, `ts-procedures/http`) to determine file types.
-3. Check each file against the categorized checklist in `checklist.md`.
-4. Output findings grouped by severity.
+2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/express-rpc`, `ts-procedures/hono-rpc`, `ts-procedures/hono-stream`, `ts-procedures/hono-api`, `ts-procedures/http`, `ts-procedures/http-docs`) to determine file types.
+3. Check each file against the categorized checklist in [checklist.md](checklist.md).
+4. For detailed code examples of each violation pattern, reference [anti-patterns.md](../guide/anti-patterns.md) — it shows 20 common mistakes with before/after code fixes and severity ratings.
+5. Output findings grouped by severity.
 
 ## Output Format
 
@@ -47,7 +40,9 @@ After individual findings, provide:
 - Total findings by severity
 - Overall assessment (healthy / needs attention / significant issues)
 - Top 3 priorities to address
+- If structural issues found, suggest `/ts-procedures:scaffold <type> <Name>` to generate correct implementations
 
 ## Reference
 
-See `checklist.md` for the complete categorized checklist by file type.
+See [checklist.md](checklist.md) for the complete categorized checklist by file type.
+See [anti-patterns.md](../guide/anti-patterns.md) for detailed code examples of each violation.

package/agent_config/claude-code/skills/scaffold/SKILL.md

@@ -1,38 +1,28 @@
 ---
 name: scaffold
-description: "Scaffold ts-procedures code with correct patterns. Usage: /ts-procedures:scaffold <type> <Name>"
-invocable_by:
-  - user
-  - model
-user_instructions: |
-  Usage: /ts-procedures:scaffold <type> <Name>
-
-  Types: procedure, stream-procedure, express-rpc, hono-rpc, hono-stream, hono-api
-
-  Examples:
-    /ts-procedures:scaffold procedure GetUser
-    /ts-procedures:scaffold stream-procedure StreamActivity
-    /ts-procedures:scaffold express-rpc UserApi
-    /ts-procedures:scaffold hono-rpc OrderApi
-    /ts-procedures:scaffold hono-stream LiveFeed
-    /ts-procedures:scaffold hono-api ProductApi
+description: "Generate ts-procedures implementations with correct patterns — procedures, streams, Express RPC, Hono RPC, Hono streaming, REST APIs, and client setup."
+argument-hint: "<type> <Name>"
+allowed-tools: Read Write
 ---
 
 # Scaffold ts-procedures Code
 
-Parse `$ARGUMENTS` as `<type> <Name>` (case-insensitive type, PascalCase Name).
+Scaffold a `$0` ts-procedures implementation named `$1`.
+
+If either argument is missing, ask the user for `<type>` and `<Name>`.
 
 ## Instructions
 
-1. Parse the arguments. If missing, ask the user for `<type>` and `<Name>`.
-2. Derive placeholder variants from the provided PascalCase Name:
+1. Validate `$0` is a recognized type (see table below). Case-insensitive.
+2. Validate `$1` is PascalCase (e.g., `UserProfile`).
+3. Derive placeholder variants from the provided PascalCase Name:
    - `{{Name}}` — PascalCase as given (e.g., `UserProfile`)
    - `{{name}}` — camelCase (e.g., `userProfile`)
    - For URL scopes and file paths, use kebab-case (e.g., `user-profile`)
-3. Read the template file from `templates/<type>.md` in this skill directory.
-4. Replace all `{{Name}}` and `{{name}}` placeholders with the appropriate variants.
-5. Generate the implementation file(s) following the template exactly.
-6. Also generate a colocated test file following ts-procedures test conventions.
+4. Read the template file from `${CLAUDE_SKILL_DIR}/templates/$0.md`.
+5. Replace all `{{Name}}` and `{{name}}` placeholders with the appropriate variants.
+6. Generate the implementation file(s) following the template exactly.
+7. Also generate a colocated test file following ts-procedures test conventions.
 
 ## Valid Types
 
@@ -44,6 +34,7 @@ Parse `$ARGUMENTS` as `<type> <Name>` (case-insensitive type, PascalCase Name).
 | `hono-rpc` | `templates/hono-rpc.md` | `{{Name}}.rpc.ts`, `{{Name}}.rpc.test.ts` |
 | `hono-stream` | `templates/hono-stream.md` | `{{Name}}.stream-rpc.ts`, `{{Name}}.stream-rpc.test.ts` |
 | `hono-api` | `templates/hono-api.md` | `{{Name}}.api.ts`, `{{Name}}.api.test.ts` |
+| `client` | `templates/client.md` | `{{Name}}.client.ts`, `{{Name}}.client.test.ts` |
 
 ## Rules
 
@@ -54,3 +45,7 @@ Parse `$ARGUMENTS` as `<type> <Name>` (case-insensitive type, PascalCase Name).
 - Use TypeBox for schema definitions (`import { Type } from 'typebox'`).
 - AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
 - Test files use `describe`/`test` from vitest.
+
+## Workflow
+
+Use the **ts-procedures-architect** agent to plan your API structure first, then scaffold each procedure. After scaffolding, use `/ts-procedures:review <path>` to validate the implementation.