Strengthen agent rules from error details porting learnings (#12)

Author: parthban-db

.agent/rules/libraries.mdc

@@ -0,0 +1,23 @@
+---
+description: Guidelines for choosing libraries over hand-rolled solutions.
+scope: all source files
+enforcement: strict
+globs: ["packages/**/src/**/*.ts"]
+---
+
+# Libraries over Hand-Rolling
+
+Prefer established ecosystem libraries over hand-rolled solutions for common
+tasks like validation, parsing, and serialization. For example, use Zod for
+runtime type validation instead of writing manual type guards and validation
+helpers.
+
+When proposing a library, justify the choice with concrete references (docs,
+API examples). Do not assert that something is "idiomatic" or "standard"
+without pointing to where that convention is documented.
+
+## Current Libraries
+
+| Task                          | Library | Notes                          |
+| ----------------------------- | ------- | ------------------------------ |
+| Runtime type validation / JSON unmarshalling | Zod     | Used for API wire-format parsing |

.agent/rules/porting.mdc

@@ -20,6 +20,11 @@ or reword them. Translate Go `//` comments to JSDoc (`/** */`) format for
 exported symbols, but keep the full content including multi-paragraph
 explanations and examples.
 
+**Do not add documentation beyond what the Go SDK has.** If a Go type or
+function has no doc comment, the TypeScript version should not have one either.
+Do not invent explanations, add `@packageDocumentation` summaries, or expand
+on what Go provides.
+
 ```go
 // OutOfRange means the operation was attempted past the valid range.
 // E.g., seeking or reading past end of file.
@@ -52,3 +57,54 @@ TypeScript:
 
 Each Go package that is separately importable should be a separate directory
 with its own `index.ts` and a corresponding subpath export in `package.json`.
+
+## Naming
+
+Names in the TypeScript implementation must be idiomatic TypeScript. Do not
+reference the source language in variable, function, or type names.
+
+```typescript
+// Good — describes what the schema does.
+const nullishString = z.string().nullish().transform(v => v ?? '');
+
+// Bad — references Go in the name.
+const goString = z.string().nullish().transform(v => v ?? '');
+```
+
+## Tests
+
+Port **all** test cases from the Go SDK. Do not selectively skip tests. When a
+Go test case cannot be directly ported (e.g. because of a language difference
+like `json.RawMessage` vs already-parsed JSON), explain the omission to the
+user and get confirmation before skipping.
+
+Use the same test structure as the Go SDK. Go table-driven tests map to
+Vitest's `it.each`:
+
+```go
+// Go
+testCases := []struct{ name string; input int; want int }{
+    {"positive", 1, 1},
+    {"zero", 0, 0},
+}
+for _, tc := range testCases {
+    t.Run(tc.name, func(t *testing.T) { ... })
+}
+```
+
+```typescript
+// TypeScript equivalent
+const testCases: {name: string; input: number; want: number}[] = [
+  {name: 'positive', input: 1, want: 1},
+  {name: 'zero', input: 0, want: 0},
+];
+it.each(testCases)('$name', ({input, want}) => { ... });
+```
+
+## Deviations from Go
+
+When the TypeScript implementation must differ from Go (e.g. different function
+signatures, different input types, skipped tests), **explain the deviation to
+the user** before proceeding. Do not silently change behaviour or add comments
+in the code about Go differences — keep the codebase clean of porting
+artifacts.

.agent/rules/testing.mdc

@@ -53,6 +53,31 @@ describe('PatCredentials', () => {
 });
 ```
 
+## Table-Driven Tests
+
+When multiple test cases share the same business logic and only differ in
+input/output data, use table-driven tests with `it.each`. Do not write
+separate `it` blocks for each case.
+
+```typescript
+// Good — table-driven.
+const testCases: {name: string; input: string; want: number}[] = [
+  {name: 'positive', input: '1', want: 1},
+  {name: 'zero', input: '0', want: 0},
+];
+it.each(testCases)('$name', ({input, want}) => {
+  expect(parse(input)).toBe(want);
+});
+
+// Bad — separate blocks with duplicated logic.
+it('should parse positive', () => {
+  expect(parse('1')).toBe(1);
+});
+it('should parse zero', () => {
+  expect(parse('0')).toBe(0);
+});
+```
+
 ## Assertions
 
 Use Vitest's `expect` API. Prefer specific matchers over generic ones.

.agent/rules/typescript.mdc

@@ -85,7 +85,10 @@ export default class TokenCache { ... }
 
 ### 2.5 Export Discipline
 
-- Only export symbols that are used outside the module.
+- Only export symbols that consumers of the package need. Keep implementation
+  details (internal helpers, parse functions, schemas) unexported. If a symbol
+  is only used within the package or by tests, do not export it from
+  `index.ts`.
 - Never use `export let`. Use a getter function if the value must change.
 - Do not create container classes with only static members. Export individual
   constants and functions instead.
@@ -708,7 +711,39 @@ effects in `afterEach` or `afterAll` blocks.
 
 ---
 
-## 15. Platform Compatibility
+## 15. Code Uniformity
+
+Keep similar code paths uniform. If multiple cases follow the same pattern,
+they should all use the same approach. Do not special-case one variant unless
+there is a clear, documented reason.
+
+```typescript
+// Good — all cases follow the same pattern.
+case ERROR_INFO_TYPE: {
+  const r = errorInfoSchema.safeParse(raw);
+  if (!r.success) return false;
+  ed.errorInfo = r.data;
+  return true;
+}
+case RETRY_INFO_TYPE: {
+  const r = retryInfoSchema.safeParse(raw);
+  if (!r.success) return false;
+  ed.retryInfo = r.data;
+  return true;
+}
+
+// Bad — one case uses a different approach for no good reason.
+case RETRY_INFO_TYPE: {
+  const parsed = tryParseRetryInfo(raw);
+  if (parsed === undefined) return false;
+  ed.retryInfo = parsed;
+  return true;
+}
+```
+
+---
+
+## 16. Platform Compatibility
 
 This SDK targets both Node.js (>= 18) and browsers.
 

AGENTS.md

@@ -55,6 +55,7 @@ self-contained and includes its scope, enforcement level, and examples.
 | `packages.mdc`         | Package scaffolding and conventions    |
 | `testing.mdc`          | Testing conventions                    |
 | `porting.mdc`          | Porting code from the Go reference SDK |
+| `libraries.mdc`        | Library selection over hand-rolling    |
 
 ## Common Commands
 
@@ -91,7 +92,11 @@ npm run clean
 
 1. **Read the rules.** Start with `.agent/rules/typescript.mdc`.
 2. **Understand existing code.** Read neighbouring files before editing.
-3. **Run checks.** After every change run `npm run lint && npm run typecheck`.
+3. **Run checks.** After every change run
+   `npm run format && npm run lint && npm run typecheck`.
 4. **Run tests.** Confirm nothing is broken with `npm test`.
 5. **Comments are sentences.** Every comment must be a proper sentence ending
    with a period.
+6. **Back up claims.** When proposing a design decision or asserting a
+   convention, provide concrete references (documentation, API links). Do not
+   state something is "idiomatic" or "standard" without evidence.