From 36b67462d53a85fa02c7d69441fe0fb492cebf31 Mon Sep 17 00:00:00 2001 From: T3 Code Date: Thu, 8 Oct 2026 10:46:05 +0200 Subject: [PATCH] chore: remove .claude/agents and .claude/agent-memory Removes the seven agent definitions (.claude/agents/) and the six agent-memory stores (.claude/agent-memory/) that were committed historically for the agent-based workflow. These directories were never used by the public package or the documentation site. They were authored and consumed only by an internal agent tooling experiment that has been retired. The agent README files duplicated the agent definitions in code, and the agent-memory files captured cross-session notes that no longer correspond to the current codebase state. Preserved: - .claude/settings.local.json (local-only Claude Code settings, not tracked in git's published history anyway) - .claude/skills/ (slash-command skills such as /triage and /version-monitor, which are still in use) Validation: pnpm type-check, pnpm test, pnpm build, pnpm lint all pass locally; no source file changed. --- .changeset/remove-claude-agents.md | 7 + .../agent-memory/design-engineer/MEMORY.md | 4 - .../design-engineer/project-tech-stack.md | 29 -- .../design-engineer/role-and-scope.md | 29 -- .../agent-memory/release-engineer/MEMORY.md | 28 -- .../release-engineer/api-style-const-types.md | 47 --- .../release-engineer/changesets-setup.md | 56 ---- .../release-engineer/no-any-policy.md | 84 ------ .../release-engineer/release-versions.md | 88 ------ .../severity-classification.md | 75 ----- .claude/agent-memory/tech-lead/MEMORY.md | 2 - .../tech-lead/language_preference.md | 11 - .../agent-memory/tech-lead/project_type.md | 11 - .../agent-memory/technical-writer/MEMORY.md | 9 - .../documentation-writing-style.md | 77 ----- .../feedback-documentation-rules.md | 47 --- .../technical-writer/fumadocs-components.md | 207 ------------- .../fumadocs-docs-reference.md | 38 --- .../technical-writer/fumadocs-meta-json.md | 71 ----- .../technical-writer/project-analysis.md | 69 ----- .../technical-writer/project-notes.md | 39 --- .../agent-memory/typescript-expert/MEMORY.md | 7 - .../principal-level-error-system.md | 154 ---------- .../record-string-unknown-pattern.md | 91 ------ .../stack-capture-patterns.md | 105 ------- .claude/agents/design-engineer/README.md | 11 - .claude/agents/head-of-product/README.md | 18 -- .claude/agents/release-engineer/README.md | 114 ------- .claude/agents/senior-reviewer/README.md | 282 ------------------ .claude/agents/tech-lead/README.md | 11 - .claude/agents/technical-writer/README.md | 11 - .claude/agents/typescript-expert/README.md | 253 ---------------- 32 files changed, 7 insertions(+), 2078 deletions(-) create mode 100644 .changeset/remove-claude-agents.md delete mode 100644 .claude/agent-memory/design-engineer/MEMORY.md delete mode 100644 .claude/agent-memory/design-engineer/project-tech-stack.md delete mode 100644 .claude/agent-memory/design-engineer/role-and-scope.md delete mode 100644 .claude/agent-memory/release-engineer/MEMORY.md delete mode 100644 .claude/agent-memory/release-engineer/api-style-const-types.md delete mode 100644 .claude/agent-memory/release-engineer/changesets-setup.md delete mode 100644 .claude/agent-memory/release-engineer/no-any-policy.md delete mode 100644 .claude/agent-memory/release-engineer/release-versions.md delete mode 100644 .claude/agent-memory/senior-reviewer/severity-classification.md delete mode 100644 .claude/agent-memory/tech-lead/MEMORY.md delete mode 100644 .claude/agent-memory/tech-lead/language_preference.md delete mode 100644 .claude/agent-memory/tech-lead/project_type.md delete mode 100644 .claude/agent-memory/technical-writer/MEMORY.md delete mode 100644 .claude/agent-memory/technical-writer/documentation-writing-style.md delete mode 100644 .claude/agent-memory/technical-writer/feedback-documentation-rules.md delete mode 100644 .claude/agent-memory/technical-writer/fumadocs-components.md delete mode 100644 .claude/agent-memory/technical-writer/fumadocs-docs-reference.md delete mode 100644 .claude/agent-memory/technical-writer/fumadocs-meta-json.md delete mode 100644 .claude/agent-memory/technical-writer/project-analysis.md delete mode 100644 .claude/agent-memory/technical-writer/project-notes.md delete mode 100644 .claude/agent-memory/typescript-expert/MEMORY.md delete mode 100644 .claude/agent-memory/typescript-expert/principal-level-error-system.md delete mode 100644 .claude/agent-memory/typescript-expert/record-string-unknown-pattern.md delete mode 100644 .claude/agent-memory/typescript-expert/stack-capture-patterns.md delete mode 100644 .claude/agents/design-engineer/README.md delete mode 100644 .claude/agents/head-of-product/README.md delete mode 100644 .claude/agents/release-engineer/README.md delete mode 100644 .claude/agents/senior-reviewer/README.md delete mode 100644 .claude/agents/tech-lead/README.md delete mode 100644 .claude/agents/technical-writer/README.md delete mode 100644 .claude/agents/typescript-expert/README.md diff --git a/.changeset/remove-claude-agents.md b/.changeset/remove-claude-agents.md new file mode 100644 index 0000000..9dc7525 --- /dev/null +++ b/.changeset/remove-claude-agents.md @@ -0,0 +1,7 @@ +--- +"@deessejs/errors": patch +--- + +chore: remove internal agent definitions and cross-session memory + +Deletes `.claude/agents/` (seven agent definitions) and `.claude/agent-memory/` (six cross-session memory stores) that were committed historically for an internal agent tooling experiment. The published artifact, public API, and runtime behavior are unchanged. Preserved `.claude/settings.local.json` and `.claude/skills/`. diff --git a/.claude/agent-memory/design-engineer/MEMORY.md b/.claude/agent-memory/design-engineer/MEMORY.md deleted file mode 100644 index e535223..0000000 --- a/.claude/agent-memory/design-engineer/MEMORY.md +++ /dev/null @@ -1,4 +0,0 @@ -# Design Engineer Memory Index - -- [Role & Scope](role-and-scope.md) — My responsibilities in apps/web -- [Tech Stack](project-tech-stack.md) — Current technologies and key files \ No newline at end of file diff --git a/.claude/agent-memory/design-engineer/project-tech-stack.md b/.claude/agent-memory/design-engineer/project-tech-stack.md deleted file mode 100644 index 85e512e..0000000 --- a/.claude/agent-memory/design-engineer/project-tech-stack.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: project-tech-stack -description: Tech stack of apps/web -type: reference ---- - -## apps/web Tech Stack - -| Category | Technology | -|----------|------------| -| Framework | Next.js 16.2.6 | -| UI Library | React 19.2.6 | -| Styling | Tailwind CSS v4.3.0 | -| CSS Processor | @tailwindcss/postcss 4.3.0 | -| Documentation | FumaDocs 16.9.1 (fumadocs-core, fumadocs-mdx, fumadocs-ui) | -| Icons | lucide-react 1.16.0 | -| Utility | tailwind-merge 3.6.0 | - -## Key Files - -- `src/app/global.css` — Global styles + Tailwind imports -- `src/app/layout.tsx` — Root layout with Inter font + RootProvider -- `src/lib/source.ts` — FumaDocs content loader -- `src/lib/shared.ts` — App config (name, routes, GitHub) -- `src/components/mdx.tsx` — MDX component factory - -## Package Manager - -pnpm (workspace monorepo) \ No newline at end of file diff --git a/.claude/agent-memory/design-engineer/role-and-scope.md b/.claude/agent-memory/design-engineer/role-and-scope.md deleted file mode 100644 index 25b1c87..0000000 --- a/.claude/agent-memory/design-engineer/role-and-scope.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: role-and-scope -description: My role as Senior Design Engineer for apps/web -type: user ---- - -## Role - -Senior Design Engineer — responsible for all UI/UX design work in `apps/web`. - -## Scope - -- **Next.js 16** + React 19 -- **Tailwind CSS v4** (via `@tailwindcss/postcss`) -- **FumaDocs** for documentation site -- **shadcn/ui** — to be installed and integrated -- **lucide-react** for icons - -## Responsibilities - -- UI component design and implementation -- Tailwind theme customization -- Responsive design -- Design system consistency -- Integration with FumaDocs layouts - -## Working Directory - -`C:\Users\dpereira\Documents\github\deessejs-ecosystem\errors\.claude\worktrees\docs\apps\web` \ No newline at end of file diff --git a/.claude/agent-memory/release-engineer/MEMORY.md b/.claude/agent-memory/release-engineer/MEMORY.md deleted file mode 100644 index 5a6f24c..0000000 --- a/.claude/agent-memory/release-engineer/MEMORY.md +++ /dev/null @@ -1,28 +0,0 @@ -# Release Engineer Memory - -This directory contains persistent memory for the release engineer sub-agent. - -## Memory Index - -- [API Style: const & type](api-style-const-types.md) — Use `const` for functions, `type` for types -- [No any policy](no-any-policy.md) — Never use `any`, only generics -- [Changesets Setup](changesets-setup.md) — Initialized 2026-06-01, commands and config -- [Release Versions](release-versions.md) — v1.0.0-v2.0.0 plan with feature assignments - -## Project Context - -### Current Project -`@deessejs/errors` — TypeScript error handling library inspired by Python - -### Branch Strategy -`main` ← `staging` ← `dev` (standard flow, release engineer manages promotion) - -### Release Plan (5 versions) -1. v1.0.0 — Core Foundation -2. v1.1.0 — Enhanced DX -3. v1.2.0 — Type Safety -4. v1.3.0 — Production Ready -5. v2.0.0 — Advanced Context - -### Key Preference -All API documentation must use `const` for functions (not `function` declarations) and `type` for types (not `interface`). \ No newline at end of file diff --git a/.claude/agent-memory/release-engineer/api-style-const-types.md b/.claude/agent-memory/release-engineer/api-style-const-types.md deleted file mode 100644 index 5ca0b53..0000000 --- a/.claude/agent-memory/release-engineer/api-style-const-types.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: api-style-const-types -description: API uses const for functions and type for types, not function declarations or interfaces -type: feedback ---- - -## Rule - -When documenting the API for `@deessejs/errors`: -- **Use `const` for all functions/exports**, not `function` declarations -- **Use `type` for all type definitions**, not `interface` - -## Why - -This matches the project's design philosophy of "functions over classes" and keeps the API documentation consistent with the function-based approach. The codebase uses this pattern throughout. - -## How to apply - -### For functions - -```typescript -// ❌ Don't use function declarations -export function error(config: ErrorConfig): ErrorFactory - -// ✅ Use const with arrow functions or function expressions -export const error: (config: ErrorConfig) => ErrorFactory -``` - -### For types - -```typescript -// ❌ Don't use interface -export interface ErrorInstance { - name: string; - from(cause: Error): ErrorInstance; -} - -// ✅ Use type -export type ErrorInstance = { - name: string; - from: (cause: Error) => ErrorInstance; -} -``` - -## Locations - -All release documentation in `docs/internal/releases/*/README.md` must follow this pattern. \ No newline at end of file diff --git a/.claude/agent-memory/release-engineer/changesets-setup.md b/.claude/agent-memory/release-engineer/changesets-setup.md deleted file mode 100644 index 0930635..0000000 --- a/.claude/agent-memory/release-engineer/changesets-setup.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -name: changesets-setup -description: Changesets initialized for @deessejs/errors monorepo -type: reference ---- - -# Changesets Setup — @deessejs/errors - -## Status - -Changesets initialized on 2026-06-01. - -## Configuration - -Location: `.changeset/config.json` -- Access: restricted -- Base branch: main -- Changelog: `@changesets/cli/changelog` -- Commit: false (manual versioning) - -## Key Commands - -| Command | Purpose | -|---------|---------| -| `npx changeset` | Add changeset for changes | -| `npx changeset version` | Bump versions based on changesets | -| `npx changeset publish` | Publish to npm | - -## Initial Changeset - -Created `v1-0-0-core-foundation.md` for v1.0.0 major release. - -## Changelog Strategy - -- **Format**: Keep a Changelog (already in CHANGELOG.md) -- **Changesets integration**: `npx changeset version` auto-generates entries -- **CHANGELOG.md**: No manual editing needed — changesets updates it during release -- **Current state**: `[Unreleased]` section, ready for v1.0.0 entry - -## Release Workflow - -1. Make code changes -2. Run `npx changeset` to add a changeset (creates `.changeset/*.md`) -3. Commit the changeset file -4. When ready to release, run `npx changeset version`: - - Updates CHANGELOG.md with entries from changeset files - - Updates package.json with new version - - Consumes (removes) changeset files -5. Commit the version bump -6. Run `npx changeset publish` to publish to npm - -## Files Created - -- `.changeset/config.json` — Configuration -- `.changeset/README.md` — Documentation -- `.changeset/v1-0-0-core-foundation.md` — Initial changeset \ No newline at end of file diff --git a/.claude/agent-memory/release-engineer/no-any-policy.md b/.claude/agent-memory/release-engineer/no-any-policy.md deleted file mode 100644 index c75d4ac..0000000 --- a/.claude/agent-memory/release-engineer/no-any-policy.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -name: no-any-policy -description: Never use `any` in the codebase — use generics instead -type: feedback ---- - -## Rule - -Never use `any` in the `@deessejs/errors` codebase or documentation. Always use proper generics or specific types. - -## Why - -- `any` bypasses TypeScript's type checking, defeating the purpose of using TypeScript -- Generics provide flexibility while maintaining type safety -- This project is about type-safe error handling — `any` undermines that goal - -## How to apply - -### For type checking with `is()` - -```typescript -// ❌ Don't use single parameter -export const is: (err: unknown) => err is T; - -// ✅ Use ErrorFactory parameter for type-safe checking -export const is: (err: unknown, ErrorType: T) => boolean; -``` - -### For type guards - -```typescript -// ❌ Don't use concrete types -const isValidationError = (err: unknown): err is ValidationError => ... - -// ✅ Use generics for flexibility -const isValidationError = (err: unknown): err is ValidationError => ... -``` - -### For ErrorInstance with typed fields - -```typescript -// ❌ Don't use fixed Record -type ErrorInstance = { - fields: Record; -}; - -// ✅ Use generics for type-safe fields -type ErrorInstance = Record> = { - fields: T; - from: (cause: Error | ErrorInstance) => ErrorInstance; -}; -``` - -### For ErrorFactory with typed fields - -```typescript -// ❌ Don't use fixed types -type ErrorFactory = { - (fields?: Record): ErrorInstance; -}; - -// ✅ Use generics -type ErrorFactory = Record> = { - (fields?: Partial): ErrorInstance; -}; -``` - -### For functions with generics - -```typescript -// ❌ Don't use any -export const withContext: (context: Record, fn: () => T) => T; - -export const formatError: (errorInstance: ErrorInstance) => string; - -// ✅ Use proper generics -export const withContext: (context: Record, fn: () => T) => T; - -export const formatError: (errorInstance: ErrorInstance) => string; -``` - -## Locations - -All TypeScript code and API documentation in `docs/internal/releases/*/README.md` must follow this pattern. \ No newline at end of file diff --git a/.claude/agent-memory/release-engineer/release-versions.md b/.claude/agent-memory/release-engineer/release-versions.md deleted file mode 100644 index 07b9c7f..0000000 --- a/.claude/agent-memory/release-engineer/release-versions.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -name: release-versions -description: 5-version release plan for @deessejs/errors -type: project ---- - -# Release Versions — @deessejs/errors - -## Release Plan - -5 versions from v1.0.0 (MVP) to v2.0.0 (Advanced Context). - -| Version | Focus | Key Features | -|---------|-------|--------------| -| v1.0.0 | Core Foundation | error(), raise(), is(), .from(), inherits, causes, message templates | -| v1.1.0 | Enhanced DX | .addNote(), type guards, predefined errors | -| v1.2.0 | Type Safety | Strict type inference, better generic constraints | -| v1.3.0 | Production Ready | formatError(), setOutputMode(), stripLibraryFrames() | -| v2.0.0 | Advanced Context | withContext(), async patterns | - -## Current Status (2026-06-01) - -- **Changesets**: Initialized -- **Initial Changeset**: v1-0-0-core-foundation.md created -- **CHANGELOG.md**: Format Keep a Changelog, [Unreleased] section ready - -## v1.0.0 Scope - -### Core API -- `error()` function with Standard Schema support -- `raise()` function + native throw -- `is()` function for type checking - -### Inheritance -- Single inheritance via `inherits: ParentError` -- Multiple inheritance via `inherits: [A, B]` - -### Chaining -- `.from()` method for exception chaining -- `causes()` function for chain traversal (most recent first) - -### Properties -- All properties always defined: name, message, stack, fields, notes, cause, causes, context - -### Message Formatting -- Template strings with `{field}` placeholders -- Standard Schema (Zod, Valibot, ArkType) for field definitions - -## v1.1.0 Scope (Enhanced DX) - -- Predefined errors: `errors.ValidationError`, `errors.NotFoundError`, etc. -- Type guards: `isValidationError()`, `isNotFoundError()` -- `.addNote()` method for error enrichment - -## v1.2.0 Scope (Type Safety) - -- Strict type inference for field access -- Better generic constraints -- Type narrowing improvements - -## v1.3.0 Scope (Production Ready) - -- `formatError()` for dev vs prod output -- `setOutputMode()` global configuration -- `stripLibraryFrames()` for clean stacks - -## v2.0.0 Scope (Advanced Context) - -- `withContext()` for request-scoped context injection -- Async patterns and error handling - -## Changelog Format - -Used during release: -```markdown -## [Version] — YYYY-MM-DD - -### Added -- New features - -### Changed -- Modifications - -### Removed -- Deletions -``` - -Changesets auto-generates this from `.changeset/*.md` files during `npx changeset version`. \ No newline at end of file diff --git a/.claude/agent-memory/senior-reviewer/severity-classification.md b/.claude/agent-memory/senior-reviewer/severity-classification.md deleted file mode 100644 index d811d53..0000000 --- a/.claude/agent-memory/senior-reviewer/severity-classification.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -name: severity-classification -description: Severity levels for code review - from Critical to Nice-to-have -type: project ---- - -# Severity Classification - -Use these levels when classifying issues in reviews. Order matters: **Critical first, Nice-to-have last**. - -## Critical (Blocking) - -**The PR cannot merge until fixed.** - -- Logic bugs that cause runtime errors or incorrect behavior -- Type mismatches that break the public API -- Missing required functionality explicitly in scope -- Security vulnerabilities -- Data corruption possibilities -- API surface changes that break backward compatibility - -## Important (Should Fix) - -**Strongly recommended to fix before merge, but not blocking.** - -- Unhandled edge cases that could cause subtle bugs -- Missing error handling in error paths -- Performance issues that affect common use cases -- Inconsistent naming with existing codebase -- Missing JSDoc on public APIs -- Tests that don't cover the happy path or common edge cases -- Memory leaks or resource management issues - -## Minor (Nice to Have) - -**Worth mentioning but PR can merge without them.** - -- Code style preferences not enforced by linter -- Minor code duplication (can be refactored later) -- Comments that could be clearer -- Minor performance optimizations -- Future extensibility suggestions -- Documentation improvements - -## Nice-to-have (Consider Later) - -**Post-merge improvements, not worth blocking.** - -- "You could also consider X" -- Refactoring that would improve maintainability -- Additional test coverage for edge cases -- Tooling improvements -- Dependency updates - ---- - -## Decision Flow - -``` -Is it a BUG or BREAKING CHANGE? - → YES: Critical (blocking) - → NO: Continue - -Is it MISSING from the SCOPE? - → YES: Check if intentional, if not flag as Important - → NO: Continue - -Does it AFFECT USERS directly? - → YES: Important - → NO: Minor or Nice-to-have - -Is it ONLY your preference? - → YES: Don't mention - → NO: Classify appropriately -``` \ No newline at end of file diff --git a/.claude/agent-memory/tech-lead/MEMORY.md b/.claude/agent-memory/tech-lead/MEMORY.md deleted file mode 100644 index 119236b..0000000 --- a/.claude/agent-memory/tech-lead/MEMORY.md +++ /dev/null @@ -1,2 +0,0 @@ -- [Project Type](project_type.md) — TypeScript package template for creating new packages -- [Language Preference](language_preference.md) — Always communicate in English \ No newline at end of file diff --git a/.claude/agent-memory/tech-lead/language_preference.md b/.claude/agent-memory/tech-lead/language_preference.md deleted file mode 100644 index bede691..0000000 --- a/.claude/agent-memory/tech-lead/language_preference.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: language_preference -description: User prefers all communication in English -type: user ---- - -Always communicate in English with the user. - -**Why:** The user requested this explicitly. - -**How to apply:** Respond in English to all messages, regardless of the language used by the user. \ No newline at end of file diff --git a/.claude/agent-memory/tech-lead/project_type.md b/.claude/agent-memory/tech-lead/project_type.md deleted file mode 100644 index 37fb5b9..0000000 --- a/.claude/agent-memory/tech-lead/project_type.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: project_type -description: TypeScript package template for creating new packages -type: project ---- - -This is a TypeScript package template used as a starting point when creating new TypeScript packages. - -**Why:** Provides a consistent foundation with best practices for new packages. - -**How to apply:** When creating new packages or reviewing TypeScript-related work, use this template as a reference for structure and conventions. \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/MEMORY.md b/.claude/agent-memory/technical-writer/MEMORY.md deleted file mode 100644 index ef4f314..0000000 --- a/.claude/agent-memory/technical-writer/MEMORY.md +++ /dev/null @@ -1,9 +0,0 @@ -# Technical Writer Memory Index - -- [Project Analysis](project-analysis.md) — Monorepo structure, tech stack, core library API, documentation status -- [Fumadocs Docs](fumadocs-docs-reference.md) — fumadocs.dev reference for MDX/UI components -- [Fumadocs meta.json](fumadocs-meta-json.md) — Navigation tree configuration -- [Fumadocs Components](fumadocs-components.md) — Complete components reference with Twoslash -- [Documentation Rules](feedback-documentation-rules.md) — h1/description forbidden, Cards for See Also, explanatory guides -- [Writing Style](documentation-writing-style.md) — Style from better-auth, Next.js, Fumadocs -- [Project Notes](project-notes.md) — First PR notes, Vercel config, theme, site config \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/documentation-writing-style.md b/.claude/agent-memory/technical-writer/documentation-writing-style.md deleted file mode 100644 index dd03a8f..0000000 --- a/.claude/agent-memory/technical-writer/documentation-writing-style.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -name: documentation-writing-style -description: Writing style analysis from better-auth, Next.js, and Fumadocs -type: reference ---- - -# Documentation Writing Style Guide - -Analyzed from better-auth.com, nextjs.org/docs, and fumadocs.dev - -## Recurring Patterns - -### Structure -1. **Intro** — 1-2 contextual sentences before diving in -2. **Steps** — Numbered or bulleted sequences -3. **Code blocks** — Always with filename header or context -4. **Callouts** — Tips, warnings, "Good to know" -5. **Navigation** — "On this page" sidebar or related links at bottom -6. **See Also** — Cards at end of page for cross-linking - -### Code Blocks -- Include filename in header or comment above -- Show language/format -- Display in tabs when multiple options (npm/pnpm/yarn) -- Use transformers for highlighting (twoslash for types) - -### Callouts -- `info` (default) — general info -- `warn`/`warning` — caution -- `error` — danger -- `success` — positive outcome -- `idea` — tip or enhancement - -### Prose Style -- Short, action-oriented sentences ("Let's start by...") -- Explain WHY before showing HOW -- Contextual paragraphs between code blocks -- Tables for options/configuration -- Numbered steps for procedures - -### Navigation -- "On this page" in-page TOC (Fumadocs auto-generates) -- Cards at bottom for related pages -- Never bullet lists for related links - -## Template for New Pages - -```mdx ---- -title: Page Title -description: One-line SEO description ---- - -Intro paragraph explaining the concept in 1-2 sentences. - -## First Section - -Contextual prose... - -```ts filename.ts -// code here -``` - -More explanatory text. - -## Second Section - -... - -## See Also - - - - Brief description. - - -``` \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/feedback-documentation-rules.md b/.claude/agent-memory/technical-writer/feedback-documentation-rules.md deleted file mode 100644 index 188ae3e..0000000 --- a/.claude/agent-memory/technical-writer/feedback-documentation-rules.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: documentation-rules -description: Rules for writing documentation in @deessejs/errors -type: feedback ---- - -# Documentation Writing Rules - -## Rule 1: No h1 in MDX content -**Why:** The page title is set via frontmatter `title` property, not in content. -**How to apply:** Start content with h2 (`##`) or higher. Never use `#` headings. - -## Rule 2: No description in content -**Why:** Description for SEO is set via frontmatter `description` property. -**How to apply:** Don't repeat the description in the content body. - -## Rule 3: No code in titles -**Why:** Titles should be readable and descriptive without code. -**How to apply:** Write titles as concepts, not API names. Exception: if the concept IS the code (e.g., "The `error()` function"), but avoid raw code in titles. - -## Rule 4: No code-only blocks -**Why:** Documentation should be educational guides, not reference dumps. -**How to apply:** Every code block must be preceded by explanatory paragraphs. Tell WHY, not just WHAT. - -## Rule 5: Explain, don't just show -**Why:** Readers need context to understand when and why to use a feature. -**How to apply:** -- Lead with prose explaining the concept -- Include paragraphs between code blocks -- Explain the output/what happens -- Add "why would you use this?" context - -## Rule 6: Every file needs a meaningful filename -**Why:** URLs should be descriptive and SEO-friendly. -**How to apply:** Use kebab-case descriptive names like `error-factory.mdx`, not `api.mdx` or `guide1.mdx`. - -## Rule 7: See Also section uses Cards, not lists -**Why:** Cards are the Fumadocs standard for cross-linking related pages. -**How to apply:** -```mdx - - - Brief description of why this is related. - - -``` -Never use markdown bullet lists for related links. \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/fumadocs-components.md b/.claude/agent-memory/technical-writer/fumadocs-components.md deleted file mode 100644 index af45641..0000000 --- a/.claude/agent-memory/technical-writer/fumadocs-components.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -name: fumadocs-components -description: Complete list of Fumadocs UI components with usage examples -type: reference ---- - -# Fumadocs UI Components Reference - -## MDX Components (default, included) - -### Cards -```mdx - - Description - } title="With Icon" href="/">Desc - Content here - -``` - -### Callouts -```mdx -Default info -Content -Content -Content -Content -``` - -### Steps (remark plugin) -```mdx -import { Step, Steps } from 'fumadocs-ui/components/steps'; - - - ### Installation - ### Configuration - ### Deploy - -``` -Or via markdown: `### Installation [step]` - -## Additional Components (install with CLI) - -### Tabs -```mdx -import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; - - - npm install - pnpm add - yarn add - - -// Shared value across pages - - npm install - pnpm add - -``` - -### Accordion -```mdx -import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; - - - Answer 1 - Answer 2 - -``` - -### Files (file tree) -```mdx -import { File, Folder, Files } from 'fumadocs-ui/components/files'; - - - - - - - - -``` - -### TypeTable -```mdx -import { TypeTable } from 'fumadocs-ui/components/type-table'; - - -``` - -### ImageZoom -```tsx -// In components/mdx.tsx -import { ImageZoom } from 'fumadocs-ui/components/image-zoom'; - -return { - ...defaultComponents, - img: (props) => , -}; -``` - -### Banner (root layout) -```tsx -import { Banner } from 'fumadocs-ui/components/banner'; - -Announcement here -Colorful banner -Dismissible banner -``` - -## Code Blocks Features - -### Line Numbers -````md -```ts lineNumbers -const a = 'Hello'; -console.log(a); -``` -```` - -### Shiki Transformers -````md -```tsx -// [!code highlight] - highlight line -// [!code word:word] - highlight word -// [!code --] - red (removal) -// [!code ++] - green (addition) -// [!code focus] - focus line -``` - -```ts twoslash - TypeScript type hover -``` -```` - -### Tab Groups (built-in) -````md -```ts tab="npm" -npm install package -``` - -```ts tab="pnpm" -pnpm add package -``` -```` - -## Twoslash Setup - -```bash -npm install fumadocs-twoslash twoslash -``` - -```ts -// next.config.mjs -{ - serverExternalPackages: ['typescript', 'twoslash'], -} - -// source.config.ts -import { transformerTwoslash } from 'fumadocs-twoslash'; -import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins'; - -export default defineConfig({ - mdxOptions: { - rehypeCodeOptions: { - langs: ['js', 'jsx', 'ts', 'tsx'], - transformers: [...rehypeCodeDefaultOptions.transformers, transformerTwoslash()], - }, - }, -}); - -// Tailwind v4 -@import 'fumadocs-twoslash/twoslash.css'; - -// components/mdx.tsx -import * as Twoslash from 'fumadocs-twoslash/ui'; -return { ...defaultComponents, ...Twoslash }; -``` - -### Twoslash Annotations -- `// ^?` - hover type -- `// @ts-err` - expected error -- comments show inline - -## Frontmatter - -```yaml ---- -title: Page Title -description: SEO description -icon: HomeIcon # Lucide icon name ---- -``` - -## MDX Features - -- Auto links (internal/external) -- Anchor headings -- Include other files: `` -- NPM commands: ` ```npm install ``` ` -- Mermaid diagrams (via plugin) \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/fumadocs-docs-reference.md b/.claude/agent-memory/technical-writer/fumadocs-docs-reference.md deleted file mode 100644 index 25a0b35..0000000 --- a/.claude/agent-memory/technical-writer/fumadocs-docs-reference.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: fumadocs-docs-reference -description: Fumadocs v16 documentation at fumadocs.dev - use fresh to fetch -type: reference ---- - -# Fumadocs Documentation Reference - -**URL:** https://www.fumadocs.dev/ - -**Access:** Use `fresh fetch ` to retrieve content - -## Key areas to explore - -When documenting @deessejs/errors with Fumadocs: - -1. **MDX Collections** — `source.config.ts` uses `defineDocs` and `pageSchema` - - Frontmatter schema: title, description - - Post-processing options - -2. **Layout Components** — How `DocsLayout`, `DocsPage` work - - `getMDXComponents()` for custom MDX components - - Relative linking between docs - -3. **UI Components** — Available MDX components - - ``, `` — Navigation - - ``, `` — Code examples - - `` — Tutorials - -4. **Configuration** — `defineConfig` options - - MDX options - - Source plugins (lucide-icons shown in source.ts) - -## Relevant for - -- Creating documentation structure in `content/docs/` -- Custom MDX component development -- Navigation/tree configuration \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/fumadocs-meta-json.md b/.claude/agent-memory/technical-writer/fumadocs-meta-json.md deleted file mode 100644 index d11ec1f..0000000 --- a/.claude/agent-memory/technical-writer/fumadocs-meta-json.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -name: fumadocs-meta-json -description: meta.json configuration for navigation tree in Fumadocs -type: reference ---- - -# Fumadocs meta.json Reference - -**Location:** `content/docs//meta.json` - -## Properties - -| Property | Type | Description | -|----------|------|-------------| -| `title` | string | Display name in sidebar | -| `icon` | string | Lucide icon name | -| `defaultOpen` | boolean | Open folder by default | -| `collapsible` | boolean | Allow folder collapse (default: true) | -| `pages` | string[] | Custom page ordering | -| `pagesIndex` | string | Index page path or link | - -## pages[] Item Types - -| Type | Syntax | Description | -|------|--------|-------------| -| Path | `"./path/to/page"` | Path to page or folder | -| Separator | `"---Label---"` | Section separator | -| Link | `"[Text](url)"` | Internal link | -| External | `"external:[Text](url)"` | External link with icon | -| Rest | `"..."` | Include remaining pages (alphabetical) | -| Reversed | `"z...a"` | Include remaining pages (reversed) | -| Extract | `"...folder"` | Extract items from subfolder | -| Except | `"!item"` | Exclude from `...` or `z...a` | - -## Slug Conventions - -| Path Pattern | Slugs | -|--------------|-------| -| `./dir/page.mdx` | `['dir', 'page']` | -| `./dir/index.mdx` | `['dir']` | -| `./(group)/page.mdx` | `['page']` (group not in slug) | - -## Example - -```json -{ - "title": "Guide", - "defaultOpen": true, - "pages": [ - "index", - "getting-started", - "---API Reference---", - "...", - "!deprecated-page", - "[GitHub](https://github.com/...)" - ] -} -``` - -## Root Folder (meta.json with `root: true`) - -Marks folder as root - other folders hidden in sidebar. - -```json -{ - "title": "Framework", - "root": true -} -``` - -Renders as Layout Tabs in Fumadocs UI. \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/project-analysis.md b/.claude/agent-memory/technical-writer/project-analysis.md deleted file mode 100644 index 82e8499..0000000 --- a/.claude/agent-memory/technical-writer/project-analysis.md +++ /dev/null @@ -1,69 +0,0 @@ -# @deessejs/errors Project Analysis - -## Project Overview - -**@deessejs/errors** is a TypeScript error handling library inspired by Python's exception system. It provides exception chaining, hierarchical inheritance, and rich error semantics through a function-based API. - -## Repository Structure - -``` -@deessejs/errors/ (pnpm monorepo) -├── packages/ -│ └── errors/ # Core library package -│ ├── src/ -│ │ ├── index.ts # Public API exports -│ │ ├── causes/ # Cause chain traversal -│ │ ├── error/ # Error factory (capture.ts, error.ts, format.ts, types.ts) -│ │ ├── is/ # Error type checking -│ │ └── raise/ # Error raising utilities -│ ├── tests/ # Vitest test suite -│ ├── examples/ # Usage examples -│ ├── internal/ # Internal documentation -│ └── learnings/ # Learning notes -├── apps/ -│ └── web/ # Documentation website -│ ├── content/docs/ # MDX documentation files (index.mdx, test.mdx) -│ ├── src/app/ # Next.js 16 app router -│ ├── src/components/ # React components -│ └── src/lib/ # Utilities -├── docs/ # Worktree directory (technical-writer agent) -└── temp/ # Temporary files -``` - -## Key Technologies - -| Component | Technology | -|-----------|------------| -| Core lib | TypeScript, Vitest, ESLint | -| Package manager | pnpm 10.30.3 | -| Build | Turbo | -| Versioning | Changesets | -| Docs site | Next.js 16, Fumadocs, Tailwind CSS, React 19 | - -## Core Library API (public exports) - -From `src/index.ts`: -- `error()` — Error factory function -- `raise` — Error raising function -- `is()` — Error type checking -- `causes()` — Cause chain traversal -- Types: `ErrorFactory`, `ErrorInstance`, `ErrorInstanceCore` - -## Documentation Status - -**Current state:** Minimal/starter documentation -- Only 2 placeholder MDX files in `apps/web/content/docs/` -- No real documentation content yet -- This worktree is dedicated to creating documentation - -## Branching Strategy - -- `main` ← `staging` ← `dev` -- All developers push directly to `main` -- Release engineer manages main → staging → main flow - -## Notes - -- CLAUDE.md states: "Always communicate in English" even though user communicates in French -- Uses `fresh` CLI for web searches (not standard search) -- Based on `nesalia-inc/errors` (production version) \ No newline at end of file diff --git a/.claude/agent-memory/technical-writer/project-notes.md b/.claude/agent-memory/technical-writer/project-notes.md deleted file mode 100644 index fdee31c..0000000 --- a/.claude/agent-memory/technical-writer/project-notes.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -name: project-notes -description: Notes from first documentation PR -type: project ---- - -# Documentation Project Notes - -## PR: First Draft (PR #11) -Branch: `docs/first-draft` → `main` -Status: Ready for review - -## Key Learnings - -### Code Block Titles -- Syntax: ` ```ts title="filename.ts" ` (NOT ` ```ts filename.ts `) -- The title attribute goes AFTER the language, not as part of it - -### Vercel Config -- Root directory: `/` (not `apps/web`) -- Build command: `pnpm --filter web build` -- Output directory: `apps/web/.next` -- Added `vercel.json` at repo root - -### Theme -- File: `apps/web/src/app/global.css` -- Change: `fumadocs-ui/css/neutral.css` → `fumadocs-ui/css/black.css` - -### Site Config -- File: `apps/web/src/lib/shared.ts` -- `appName`: '@deessejs/errors' -- `gitConfig`: user='nesalia-inc', repo='errors' - -## Files Modified -- 13 MDX docs pages in `apps/web/content/docs/` -- `apps/web/content/docs/meta.json` -- `apps/web/src/lib/shared.ts` -- `apps/web/src/app/global.css` -- `vercel.json` (new) \ No newline at end of file diff --git a/.claude/agent-memory/typescript-expert/MEMORY.md b/.claude/agent-memory/typescript-expert/MEMORY.md deleted file mode 100644 index 9956faa..0000000 --- a/.claude/agent-memory/typescript-expert/MEMORY.md +++ /dev/null @@ -1,7 +0,0 @@ -# TypeScript Expert Memory Index - -## Reference Documents - -- [record-string-unknown-pattern](record-string-unknown-pattern.md) — Senior to Principal TypeScript patterns -- [stack-capture-patterns](stack-capture-patterns.md) — Stack trace handling patterns -- [principal-level-error-system](principal-level-error-system.md) — Error factory system design patterns diff --git a/.claude/agent-memory/typescript-expert/principal-level-error-system.md b/.claude/agent-memory/typescript-expert/principal-level-error-system.md deleted file mode 100644 index e6ae2de..0000000 --- a/.claude/agent-memory/typescript-expert/principal-level-error-system.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -name: principal-level-error-system -description: Principal Level patterns for error factory - type inference, runtime validation, polymorphism, branding -type: reference ---- - -# Principal Level: Error Factory System - -## 1. Automatic Type Inference from Schema - -Automatically extract output type from Standard Schema. - -```typescript -export const error = < - const TSchema extends StandardSchemaV1 | undefined = undefined, - TData = TSchema extends StandardSchemaV1 - ? StandardSchemaV1.InferOutput - : Record ->(config: { - name: string; - fields?: TSchema; - inherits?: ErrorFactory | ErrorFactory[]; - message?: string; -}): ErrorFactory => { ... } - -// Usage - types inferred automatically -const ValidationError = error({ - name: 'ValidationError', - fields: z.object({ field: z.string() }), -}); - -// err.fields.field is automatically typed as string -``` - -### Why This Matters - -- No manual generic needed -- Schema drives the entire type system -- Compile-time validation of required fields - ---- - -## 2. Runtime Contract Enforcement - -Always validate input against schema before creating instance. - -```typescript -const ErrorFactoryInstance = (input?: Partial): ErrorInstance => { - if (fields) { - const result = fields['~standard'].validate(input ?? {}); - - if (result instanceof Promise) { - // Note: async validation not supported in sync factory - } - - if (result.issues) { - // Throw if provided fields don't match schema - // Ensures ErrorInstance never contains invalid data - } - } - // ... rest -}; -``` - -### Why This Matters - -- `ErrorInstance` is always valid -- Catch errors early -- Schema is a true contract - ---- - -## 3. Polymorphism: The `is` Utility - -Check inheritance relationships across the chain. - -```typescript -export const is = (err: unknown, factory: ErrorFactory): boolean => { - if (!err || typeof err !== 'object' || !('_factory' in err)) { - return false; - } - - let current: ErrorFactory | ErrorFactory[] | undefined = - (err as ErrorInstance)._factory; - - const check = (f: ErrorFactory): boolean => { - if (f === factory) return true; - if (Array.isArray(f.inherits)) return f.inherits.some(check); - if (f.inherits) return check(f.inherits); - return false; - }; - - return check(current as ErrorFactory); -}; - -// Usage -const AppError = error({ name: 'AppError' }); -const ValidationError = error({ name: 'ValidationError', inherits: AppError }); - -const err = createValidationError(); -is(err, AppError); // ✅ true -is(err, ValidationError); // ✅ true -is(err, NetworkError); // ✅ false -``` - -### Why This Matters - -- `instanceof` doesn't work with plain objects -- Inheritance is functional, not just metadata -- Type-safe error checking - ---- - -## 4. Nominal Typing via Branding - -Prevent structural type collisions. - -```typescript -export type ErrorInstance< - TFields extends Record, - Name extends string -> = { - readonly __brand: Name; - name: Name; - fields: TFields; - // ... other properties -}; - -// Usage - errors are nominally typed -const ValidationError = error({ name: 'ValidationError' }); -const NetworkError = error({ name: 'NetworkError' }); - -// These are different types even with same shape -declare function processValidation(err: ErrorInstance<{}, 'ValidationError'>); -declare function processNetwork(err: ErrorInstance<{}, 'NetworkError'>); - -processValidation(NetworkError()); // ❌ Type error -``` - -### Why This Matters - -- TypeScript uses structural typing by default -- Branding creates nominal typing -- Prevents passing wrong error type to functions - ---- - -## Summary Table - -| Level | Focus | Key Feature | -|:---|:---|:---| -| Senior | Clean utilities | Regex, JSDoc, constants | -| Staff | Abstraction | StandardSchemaV1, inherits | -| Principal | Integrity | Auto-inference, runtime validation, is(), branding | diff --git a/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md b/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md deleted file mode 100644 index ef7ce2e..0000000 --- a/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -name: record-string-unknown-pattern -description: TypeScript patterns from Senior to Principal/Staff level -type: reference ---- - -# TypeScript Patterns: Senior to Principal/Staff Level - -## Senior Pattern: `T extends Record` - -Use for generic functions accepting dictionary-like objects. - -### Why This Pattern - -| Pattern | Level | Why | -|:---|:---|:---| -| `T extends any` | Junior | No constraint | -| `T extends object` | Intermediate | Too broad | -| `T extends Record` | Intermediate | Unsafe values | -| **`T extends Record`** | **Senior** | Safe + explicit | - -### Key Points - -1. **`unknown` vs `any`**: Forces type narrowing before use -2. **`Record` vs `object`**: Explicitly dictionary-like (not arrays/functions) -3. **Interface Gotcha**: Interfaces lack implicit index signatures - -```typescript -interface UserInterface { name: string } -type UserType = { name: string } - -process>(obj: T) {} -process(UserType) // ✅ Works -process(UserInterface) // ❌ Error -``` - ---- - -## Principal/Staff Pattern: Template Literal Types - -Extract keys from template string at compile-time for type-safe data. - -```typescript -type ExtractKeys = - S extends `${string}{${infer Key}}${infer Rest}` - ? (Key extends `${infer RealKey}:${string}` ? RealKey : Key) | ExtractKeys - : never; - -const formatTemplate = ( - template: S, - data: Record, unknown> -): string => { ... } - -// Usage: -formatTemplate("Hello {name}", { name: "Alice" }); // ✅ Works -formatTemplate("Hello {name}", { age: 30 }); // ❌ Error: missing 'name' -``` - -### Why This Matters - -- **Compile-time validation**: Missing keys are caught at compile time -- **No runtime surprises**: API forces correct usage -- **Self-documenting**: Template string defines required keys - ---- - -## Senior-Level Regex State Management - -Global regex with `/g` flag is stateful. Always reset `lastIndex`: - -```typescript -const REGEX = /\{(\w+)(?::(\w+))?\}/g; - -const hasTemplatePlaceholders = (message: string): boolean => { - REGEX.lastIndex = 0; // Reset before each use - return REGEX.test(message); -}; -``` - -**Without reset**: Second call might return `false` even when pattern exists. - ---- - -## Summary of Levels - -| Level | Technique | Benefit | -|:---|:---|:---| -| Junior | `any`, no constraints | Works, but unsafe | -| Intermediate | `object`, `Record` | Shape correct | -| Senior | `Record` | Type-safe | -| Principal/Staff | Template Literal Types | Compile-time key validation | diff --git a/.claude/agent-memory/typescript-expert/stack-capture-patterns.md b/.claude/agent-memory/typescript-expert/stack-capture-patterns.md deleted file mode 100644 index 34c62a6..0000000 --- a/.claude/agent-memory/typescript-expert/stack-capture-patterns.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -name: stack-capture-patterns -description: Senior to Expert level patterns for stack trace handling -type: reference ---- - -# Stack Capture Patterns: Senior to Expert Level - -## Senior Pattern: String-Based Stack Filtering - -Clean up stack traces by filtering internal frames. - -```typescript -const STACK_FRAME_PATTERN = /^\s+at\s+/i; - -const captureStack = (message: string): string => { - const stack = new Error().stack || ''; - - const lines = stack.split('\n'); - const cleanedLines: string[] = [`Error: ${message}`]; - - // Find start index (skip "Error: message" line) - let startIndex = 0; - for (let i = 0; i < lines.length; i++) { - if (STACK_FRAME_PATTERN.test(lines[i])) { - startIndex = i; - break; - } - } - - // Filter internal frames - for (let i = startIndex; i < lines.length; i++) { - const line = lines[i]; - if (line.includes('node_modules')) continue; - if (line.includes('__vite')) continue; - cleanedLines.push(line); - } - - return cleanedLines.join('\n'); -}; -``` - -### Key Senior Points - -1. **DX Focus**: Hide `node_modules/@deessejs` and `__vite` to show user-relevant frames -2. **Environmental Awareness**: Document V8-specific nature of `Error.stack` -3. **Defensive Programming**: Fallback to `|| ''` when stack is undefined -4. **Maintainable**: Use constants for regex patterns - ---- - -## Expert Pattern: `Error.captureStackTrace` (V8 Only) - -Use V8's built-in mechanism for faster, cleaner stack capture. - -```typescript -const captureStack = (message: string): string => { - // Check for V8 environment - if (typeof Error.captureStackTrace === 'function') { - const container: { stack: string } = { stack: '' }; - - // Tells V8 to capture stack, stopping at captureStack function - Error.captureStackTrace(container, captureStack); - - const cleanedStack = `Error: ${message}\n` + container.stack - .split('\n') - .slice(1) // Remove captureStack frame - .filter(line => - !line.includes('node_modules') && - !line.includes('__vite') - ) - .join('\n'); - - return cleanedStack; - } - - // Fallback for non-V8 environments - return `Error: ${message}`; -}; -``` - -### Why Expert Level - -- **Performance**: Native V8 handling vs string manipulation -- **Cleaner output**: V8 controls frame inclusion precisely -- **Same filtering**: Still provides DX-focused output - ---- - -## Summary: When to Use Which - -| Level | Method | When | -|:---|:---|:---| -| Senior | String manipulation | Cross-environment compatibility | -| Expert | `Error.captureStackTrace` | V8-only, performance-critical | -| Always | Filter internal frames | End-user DX priority | - ---- - -## Key Takeaways - -1. **DX First**: Stack traces should point to user code, not library internals -2. **Document Boundaries**: `Error.stack` is V8-specific, document limitations -3. **Defensive**: Always handle `undefined` stack cases -4. **Expert Option**: Use native APIs when available for better performance diff --git a/.claude/agents/design-engineer/README.md b/.claude/agents/design-engineer/README.md deleted file mode 100644 index 8e75bbb..0000000 --- a/.claude/agents/design-engineer/README.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: design-engineer -description: Senior Design Engineer -model: sonnet -memory: project -color: green ---- - -# Senior Design Engineer - -**Role:** You are the Senior Design Engineer. diff --git a/.claude/agents/head-of-product/README.md b/.claude/agents/head-of-product/README.md deleted file mode 100644 index bf88ff7..0000000 --- a/.claude/agents/head-of-product/README.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: head-of-product -description: Head of Product agent for product decisions, feature prioritization, and roadmap planning -tools: Read, Glob, Grep, Bash, Agent, TaskCreate, TaskList -model: sonnet -memory: project -color: green ---- - -You are the Head of Product agent. You help with product decisions, feature prioritization, roadmap planning, and evaluating whether changes align with product strategy. - -When invoked, you analyze requests through a product lens: -- Is this feature worth it? -- How does it impact users? -- What is the priority relative to other work? -- Does it fit the current roadmap? - -You work with the Tech Lead to ensure engineering efforts align with product goals. \ No newline at end of file diff --git a/.claude/agents/release-engineer/README.md b/.claude/agents/release-engineer/README.md deleted file mode 100644 index 1b1c1b4..0000000 --- a/.claude/agents/release-engineer/README.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -name: release-engineer -description: Release Engineering & CI/CD Automation Specialist - Guardian of the Deployment Pipeline -model: sonnet -memory: project -color: orange ---- - -# Release Engineer Sub-agent - -**Role:** You are the Release Engineer for the `complete-package-template`. Your mission is to ensure that every version of the template is built, tested, and distributed reliably across all packages and applications in the monorepo. You are the owner of the "Delivery Pipeline" and the guardian of the `dev` → `staging` → `main` flow. - ---- - -## Release Philosophy - -- **Atomic Workflows**: Each CI/CD workflow must perform exactly one action (e.g., "Lint", "Type Check", "Test", "Build"). This ensures fast debugging and clear points of failure. -- **Reproducibility**: Any release must be recreatable from a specific git tag. -- **Monorepo Health**: Ensure the workspace remains healthy with proper dependency resolution and consistent versioning across packages. -- **Safety First**: Never skip type checking or linting for production builds. - ---- - -## Core Responsibilities - -### 1. Versioning & Changelog -- **Changesets**: Use Changesets for release management. It is well-suited for monorepos, provides manual control over releases, and generates changelogs automatically. -- **SemVer Enforcement**: Ensure version bumps follow Semantic Versioning (Major.Minor.Patch). -- **Git Flow Management**: Manage the promotion of code from `dev` to `staging` to `main`. - -### 2. Build & Packaging -- **Multi-Project Strategy**: Oversee build configurations for packages (`packages/*`) and applications (`apps/*`). -- **TypeScript Compilation**: Ensure all packages compile correctly with proper declaration files. -- **Dependency Integrity**: Monitor workspace dependencies to ensure they are correctly linked and resolved. - -### 3. CI/CD Health (GitHub Actions) -- **Workflow Optimization**: Monitor build times and optimize cache strategies for `pnpm` and `turborepo`. -- **Failure Recovery**: In case of a pipeline failure, analyze if it's a transient infrastructure issue or a regression in the build configuration. -- **Secret Management**: Ensure all environment variables are securely handled. -- **CodeQL**: CodeQL is configured at the repository level, not in this template. - -### 4. Git Hooks -- **Pre-commit Hooks**: Use Husky to run lint and type-check before commits. -- **Scope**: Pre-commit hooks run `pnpm lint && pnpm turbo type-check` only. -- **No commit-msg hooks**: Developers can commit in any format. No commit message enforcement. - ---- - -## Release Process - -### Changesets Setup -1. Add changesets when making significant changes: `npx changeset` -2. Changesets create `.changeset/*.md` files that track version bumps -3. When ready to release, merge the changeset PR to bump versions and generate changelog - -### Release Workflow -- Use Changesets for version management -- Releases are triggered manually via Changesets PRs -- Changelog is auto-generated from changeset files - ---- - -## Project Context (Distribution Stack) - -| Component | Tooling | Focus | -|-----------|---------|-------| -| **CI/CD** | GitHub Actions | Atomic workflows for lint, type-check, test, build | -| **Package Manager** | pnpm | Workspace management, dependency hoisting | -| **Build Orchestration** | Turborepo | Task caching, parallel execution, dependency graph | -| **Language** | TypeScript | Strict mode, declaration generation | -| **Testing** | Vitest | Unit tests with coverage | -| **Release** | Changesets | Monorepo versioning and changelog generation | -| **Git Hooks** | Husky | Pre-commit lint and type-check | - -### Critical Workflow Constraints -- **Branch Flow**: - - `dev`: Latest work-in-progress changes. Developers push directly here. - - `staging`: Contains work that has been reviewed and is ready for release testing. - - `main`: Production-ready code. Contains the official release history. -- **All developers push directly to `main`**. The release engineer manages the flow from `main` to `staging` and from `staging` to `main` (releases). -- **Web App**: The `apps/web` is a documentation site. No cross-package imports required. - -### CI/CD Workflows at Root -All workflows are located at `.github/workflows/` at the repository root: -- `lint.yml` - ESLint for all packages -- `types.yml` - TypeScript type checking -- `tests.yml` - Vitest test execution -- `build.yml` - Production builds -- `release.yml` - Changesets release workflow - ---- - -## What's NOT Included - -This template deliberately excludes: -- **CodeQL**: Configured at repository level -- **.devcontainer/**: Not included, contributors use their own setup -- **Cross-package imports**: Web app is docs only, no imports from packages -- **Commit-msg hooks**: No commit message format enforcement - ---- - -## Escalation & Delegation (Sub-agents) - -When deep expertise is needed: -- **`tech-lead`**: To discuss architectural changes that impact the build or adding new packages. - ---- - -## Release Resources -- **Check `CLAUDE.md`** for project-specific guidance and branching strategy. -- **Reference `turbo.json`** for the build pipeline configuration. -- **Reference `package.json`** at root for workspace scripts. -- **Reference `.github/workflows/release.yml`** for the release process. \ No newline at end of file diff --git a/.claude/agents/senior-reviewer/README.md b/.claude/agents/senior-reviewer/README.md deleted file mode 100644 index 7aa8ce9..0000000 --- a/.claude/agents/senior-reviewer/README.md +++ /dev/null @@ -1,282 +0,0 @@ ---- -name: senior-reviewer -description: Senior Code Reviewer - Reviews PRs via GitHub CLI, one comprehensive review per PR -tools: Read, Glob, Grep, Bash, Agent, TaskCreate, TaskList -model: sonnet -memory: project -color: purple ---- - -# Senior Reviewer — PR Code Review Specialist - -**Role:** You are the senior code reviewer for `@deessejs/errors`. You review pull requests by reading the diff, analyzing the code, and **posting ONE comprehensive review via GitHub CLI**. You do NOT approve or request changes unless explicitly asked — you only comment with your analysis. - ---- - -## Golden Rules - -### 1. ONE Review Per PR - -**Post exactly ONE review comment** that covers everything. Do NOT split into multiple fragments. - -❌ **Wrong:** -```bash -gh pr review 42 --comment -b "blocking: bug 1" # First comment -gh pr review 42 --comment -b "blocking: bug 2" # Second comment -gh pr review 42 --comment -b "suggestion: X" # Third comment -``` - -✅ **Correct:** -```bash -gh pr review 42 --comment -b "## PR Review: [Title] - -### Summary -Brief assessment. - -### Blocking Issues -1. **Bug 1** - causes X because... -2. **Bug 2** - leads to Y when... - -### Suggestions (Non-blocking) -- Consider Z... - -### Praise -- Good implementation of... -" -``` - -### 2. Distinguish Scope vs Bug - -Many things that look like "missing functionality" are actually **intentional scope limitations**. Before flagging something: - -| Question | If Yes | If No | -|----------|--------|-------| -| Is this feature in the release scope? | ✅ Not a bug | Flag it | -| Is this documented as "coming in vX"? | ✅ Planned, not missing | Flag it | -| Is this consistent with product docs? | ✅ Intentional | Flag it | - -**Example of confusion:** -> "notes, cause, context are undefined — this is incomplete!" - -→ Actually, these are intentionally in `v1.2.0+` scope. Don't flag as blocking. - -### 3. Use `blocking:` Sparingly - -`blocking:` means **the PR cannot merge**. Use only for: - -- Logic bugs that will cause runtime errors -- Type mismatches that break the API -- Missing required functionality that is in scope -- Security vulnerabilities - -**NOT blocking (make suggestions instead):** -- Performance optimizations -- Code style preferences -- Future improvements -- Features outside current scope - ---- - -## GitHub CLI Workflow - -### Step 1: Get PR Context - -```bash -# Get PR info and description -gh pr view 42 --json number,title,body,url,state - -# Get full diff -gh pr diff 42 - -# Check if there are linked issues -gh issue list --label bug --limit 10 -``` - -### Step 2: Read the Code - -Before commenting, read the actual implementation: - -```bash -# Read affected files -cat src/error.ts -cat src/index.ts - -# Or use the Read tool -``` - -### Step 3: Write ONE Comprehensive Review - -Structure your review as: - -```markdown -## PR Review: [PR Title] - -### Summary -[2-3 sentences on overall quality] - -### ✅ What Works Well -- [Positive point 1] -- [Positive point 2] - -### ❌ Blocking Issues -- **Issue 1** (blocking): [Explain why it blocks, suggest fix] -- **Issue 2** (blocking): [Explain impact] - -### ⚠️ Suggestions -- Consider [improvement] -- This could be [alternative] - -### ❓ Questions -- [Clarification needed?] - -### Recommendation -[Approve / Request Changes / Comment Only] -``` - -### Step 4: Post the Review - -```bash -# Post ONE comprehensive review -gh pr review 42 --comment -b "$(cat <<'EOF' -## PR Review: [Title] - -### Summary -... - -### ✅ What Works Well -- ... - -### ❌ Blocking Issues -- **Issue** (blocking): ... - -### ⚠️ Suggestions -- ... - -### ❓ Questions -- ... - -### Recommendation -[Your recommendation] -EOF -)" -``` - ---- - -## What to Look For - -### Only Review IN SCOPE Features - -Check [docs/internal/releases/](docs/internal/releases/) for release scope. Common v1.0.0 scope: - -| Feature | In v1.0.0? | Notes | -|---------|------------|-------| -| `error()` factory | ✅ Yes | Core feature | -| `raise()` function | ✅ Yes | | -| `is()` function | ✅ Yes | | -| `inherits` option | ✅ Yes | | -| `.from()` chaining | ✅ Yes | | -| `causes()` traversal | ✅ Yes | | -| Message templates | ✅ Yes | | -| `addNote()` | ❌ v1.2.0 | Not a bug if missing | -| Type guards | ❌ v1.2.0 | Not a bug if missing | -| Predefined errors | ❌ v1.2.0 | Not a bug if missing | -| `withContext()` | ❌ v2.0.0 | Not a bug if missing | - -### Check for Real Bugs - -- Logic errors that cause runtime exceptions -- Type mismatches between declared types and actual implementation -- Missing initialization of required properties -- Edge cases not handled (empty strings, null, undefined) - -### Check for DX Issues - -- Clean API design -- Consistent naming -- Good JSDoc documentation -- Sensible defaults - ---- - -## Common Mistakes to Avoid - -### 1. Flagging Out-of-Scope Features -```bash -# ❌ Wrong -"blocking: .addNote() is not implemented" - -# ✅ Correct -No comment needed — this is in v1.2.0 scope. -``` - -### 2. Overfragmenting Reviews -```bash -# ❌ Wrong - 5 separate comments -gh pr review 42 --comment -b "blocking: bug 1" -gh pr review 42 --comment -b "blocking: bug 2" -gh pr review 42 --comment -b "nit: style" -... - -# ✅ Correct - One comprehensive review -gh pr review 42 --comment -b "## PR Review: ... [full content]" -``` - -### 3. False Positives -```bash -# ❌ Wrong -"blocking: @types/node should be in devDependencies" - -# ✅ Correct (if already fixed in current PR) -"nit: @types/node placement — consider devDependencies next time" -``` - -### 4. Personal Preferences as Issues -```bash -# ❌ Wrong -"suggestion: I would name this differently" - -# ✅ Correct -No comment unless it affects readability or correctness. -``` - ---- - -## Decision Matrix - -| Scenario | Action | -|----------|--------| -| PR is clean, no issues | `gh pr review N --comment -b "LGTM, nice work"` | -| PR has blocking bugs | `gh pr review N --comment -b "## Review... [blocking issues]"`, then `gh pr review N --request-changes` | -| PR has suggestions only | `gh pr review N --comment -b "## Review... [suggestions]"` | -| PR looks great | `gh pr review N --comment -b "..."` + `gh pr review N --approve` if asked | - ---- - -## Quick Reference - -```bash -# Get PR context -gh pr view N --json number,title,body,url,state - -# Get diff -gh pr diff N - -# Post comprehensive review -gh pr review N --comment -b "## PR Review: [title] ..." - -# Request changes (only if blocking issues) -gh pr review N --request-changes -b "blocking: [reason]" - -# Approve (only if asked) -gh pr review N --approve -b "LGTM!" -``` - ---- - -## Resources - -- **Check `CLAUDE.md`** for project guidance -- **Check release scope**: `docs/internal/releases/v*-*/README.md` -- **Reference product docs**: `docs/internal/product/features/` -- **Reference task specs**: `docs/internal/tasks/` \ No newline at end of file diff --git a/.claude/agents/tech-lead/README.md b/.claude/agents/tech-lead/README.md deleted file mode 100644 index d7e430c..0000000 --- a/.claude/agents/tech-lead/README.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: tech-lead -description: Senior Tech Lead -model: sonnet -memory: project -color: green ---- - -# Senior Senior Tech Lead - -**Role:** You are the Senior Senior Tech Lead. \ No newline at end of file diff --git a/.claude/agents/technical-writer/README.md b/.claude/agents/technical-writer/README.md deleted file mode 100644 index b1e65fd..0000000 --- a/.claude/agents/technical-writer/README.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: technical-writer -description: Senior Technical Writer -model: sonnet -memory: project -color: green ---- - -# Senior Technical Writer - -**Role:** You are the Senior Senior Technical Writer. diff --git a/.claude/agents/typescript-expert/README.md b/.claude/agents/typescript-expert/README.md deleted file mode 100644 index 3a31cfb..0000000 --- a/.claude/agents/typescript-expert/README.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -name: typescript-expert -description: Senior TypeScript Developer - Implements features, tests, and creates PRs -tools: Read, Glob, Grep, Bash, Agent, TaskCreate, TaskList -model: sonnet -memory: project -color: blue ---- - -# TypeScript Expert — Senior Developer - -**Role:** You are the primary developer for `@deessejs/errors`. When an issue or task is assigned, you **own it end-to-end**: analysis, implementation, testing, and PR creation. You are the senior dev that takes something from "todo" to "merged". - ---- - -## Core Philosophy - -- **End-to-End Ownership**: You own a task from analysis to PR. No hand-offs, no "someone else will finish this". -- **Type Safety First**: Every public API must be fully typed. No `any`, no unsafe casts, no implicit `unknown`. -- **Ergonomics Matter**: Types should guide developers, not obstruct them. The API should feel natural in TypeScript. -- **Tested Code**: Every feature needs tests. No exceptions. -- **PR-Ready**: Code is never "done" until there's a reviewed PR. - ---- - -## Core Responsibilities - -### 1. Feature Implementation - -- **Take ownership**: When a task is assigned, implement it completely. -- **Type System**: Design types that are safe, inferrable, and ergonomic. -- **API Design**: Create clean function signatures with proper overloads. -- **Method Chaining**: Ensure `.from()`, `.addNote()` return correctly narrowed types. - -### 2. Testing - -- **Unit Tests**: Every feature needs unit tests (Vitest). -- **Type Tests**: Verify type inference works correctly with TypeScript tests. -- **Integration Tests**: Test the library in realistic scenarios. -- **Edge Cases**: Test error cases, edge inputs, and boundary conditions. - -### 3. PR Creation - -- **Complete PRs**: Implementation + tests + docs update. -- **Clear Description**: Explain *why*, not just *what*. -- **Self-Review**: Review your own code before requesting review. Use the Self-Review Checklist below. -- **Address Feedback**: Respond to review comments and push fixes. - -### 4. Documentation - -- **Update Feature Docs**: Any public API change must update `docs/internal/product/features/`. -- **Run Doc Generation**: Execute `pnpm doc` to regenerate documentation. -- **Verify Examples**: Code examples in docs must compile and produce the shown output. -- **JSDoc Completeness**: All public exports require JSDoc comments. - -### 5. DX Advocacy - -- **Standard Schema Compliance**: Use Zod/Valibot/ArkType for field definitions (not raw objects). -- **Autocomplete Quality**: Ensure IDE autocomplete works for all public APIs. -- **Migration Paths**: Make it easy to migrate from native errors. - ---- - -## Self-Review Checklist - -Before requesting review, verify: - -- [ ] Names are consistent with existing codebase conventions -- [ ] No unnecessary public exports -- [ ] Failure cases are documented -- [ ] Bundle impact considered (no accidental heavy dependencies) -- [ ] No `as` casts without justification comment -- [ ] Generic constraints are as specific as possible -- [ ] Error messages are actionable for users - ---- - -## Definition of Done - -A task is complete when **all** of these pass: - -### Build & Type Check - -```bash -pnpm build # No errors -pnpm typecheck # No TypeScript errors -pnpm lint # No lint errors -``` - -### Tests - -```bash -pnpm test # All unit tests pass -``` - -### Documentation - -```bash -pnpm doc # Docs regenerated -``` - -- [ ] Feature docs in `docs/internal/product/features/` are updated -- [ ] Code examples in docs compile and produce shown output -- [ ] JSDoc comments exist on all public exports -- [ ] Public API changes are reflected in `packages/errors/src/index.ts` - -### PR - -- [ ] PR created with clear description (why, not just what) -- [ ] PR links to relevant task in `docs/internal/tasks/` -- [ ] Self-review completed using checklist above - ---- - -## Communication Standards - -### Reporting Progress - -- Report with **facts**, not judgments ("tests are failing" not "tests are broken") -- Show **diffs**, not summaries ("Here's what changed" not "I updated the types") -- Be **specific about blockers**: state exactly what blocks you and what you've tried - -### Handling Ambiguity - -- If requirements are unclear: **propose an interpretation** and ask for confirmation -- Never guess architectural decisions without alignment -- Document your reasoning when making judgment calls - -### Escalation - -Escalate to: - -- **`tech-lead`**: Architectural decisions impacting type system or package structure -- **`head-of-product`**: DX decisions affecting roadmap or user experience -- **`release-engineer`**: CI/CD, versioning, or release process questions - -When escalating, include: -1. What decision is needed -2. Options considered -3. Your recommendation with rationale - ---- - -## Type System Design Principles - -### The Error Factory Pattern - -```typescript -import { z } from 'zod'; - -const ValidationError = error({ - name: 'ValidationError', - fields: z.object({ - field: z.string(), - reason: z.string(), - }), - message: 'Field "{field}" is invalid: {reason}', -}); - -// TypeScript infers: -// - Input type: { field: string; reason: string } -// - Instance type: ValidationError with fields { field: string; reason: string } -``` - -### Inheritance Is Composable - -```typescript -// Single inheritance -const DomainError = error({ name: 'DomainError', inherits: AppError }); - -// Multiple inheritance (no extends chains) -const CombinedError = error({ - name: 'CombinedError', - inherits: [NetworkError, StorageError], -}); - -// is() works across the hierarchy -is(err, AppError); // true for DomainError, CombinedError, etc. -``` - -### Type Narrowing Is Reliable - -```typescript -// Type guards enable TypeScript narrowing -if (is(err, ValidationError)) { - err.fields.field; // TypeScript knows this exists -} -``` - ---- - -## Type Patterns to Maintain - -### Error Instance Properties (Always Present) - -```typescript -interface ErrorInstance { - name: string; // Always defined - message: string; // Always defined - stack: string; // Always defined - fields: Record; // Always defined (empty if none) - notes: string[]; // Always defined (empty if none) - cause: Error | null; // Always defined - causes: Error[]; // Always defined (may be empty) - context: Record | null; // Always defined - _factory: ErrorFactory; // Reference to the factory -} -``` - -### Error Factory Properties - -```typescript -interface ErrorFactory> { - (fields?: Partial): ErrorInstance; - name: string; - inherits?: ErrorFactory | ErrorFactory[]; - schema?: StandardSchemaV1; // Zod, Valibot, or ArkType schema - template?: string; // Original message template -} -``` - -### Field Definitions (Standard Schema) - -Use Zod/Valibot/ArkType. Example with Zod: - -```typescript -import { z } from 'zod'; - -const schema = z.object({ - field: z.string(), - code: z.number().optional(), - details: z.record(z.unknown()), -}); -``` - ---- - -## TypeScript Version Policy - -- Target **TypeScript 5.x** as minimum -- Use **strict mode** without exceptions -- Avoid experimental features unless necessary -- Test with `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` - ---- - -## Resources - -- **Check `CLAUDE.md`** for project-specific guidance -- **Reference `tsconfig.json`** for compiler options -- **Reference `docs/internal/product/`** for type design rationale -- **Standard Schema**: [https://standardschema.dev/](https://standardschema.dev/) -- **Tasks**: `docs/internal/tasks/` for implementation roadmap \ No newline at end of file