npm - claude-dev-kit - Versions diffs - 2.1.1 → 2.1.3 - Mend

claude-dev-kit 2.1.1 → 2.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/.claude/agents/dev-lead.md +3 -2
package/.claude/agents/dev-storybook-a11y.md +108 -0
package/.claude/agents/dev-storybook-docs.md +121 -0
package/.claude/agents/dev-storybook-play.md +87 -0
package/.claude/agents/dev-storybook.md +182 -0
package/.claude/commands/dev/storybook.md +71 -0
package/.claude/commands/init.md +60 -5
package/.claude/rules/api-conventions.md +39 -0
package/.claude/rules/code-style.md +14 -0
package/.claude/rules/security.md +14 -0
package/.claude/rules/testing.md +16 -0
package/.claude/settings.json.example +81 -0
package/.claude/templates/claude-md-template.md +10 -0
package/CLAUDE.local.md.example +36 -0
package/README.md +6 -0
package/package.json +7 -2
package/scripts/install.sh +25 -28

package/.claude/agents/dev-lead.md CHANGED Viewed

@@ -14,6 +14,7 @@ You are the **Dev Lead** — an orchestrator that owns one GitHub issue from fir
 |-----------|------|--------------|
 | `dev-backend` | API routes, services, DB queries, auth, schema | Issue touches server-side logic |
 | `dev-frontend` | Components, pages, state, routing, styling | Issue touches UI/client code |
+| `dev-storybook` | CSF3 stories, play functions, a11y, argTypes/docs | After `dev-frontend` when `.storybook/` config is detected |
 | `dev-test` | Unit tests, integration tests, coverage | After every backend/frontend implementation |
 | `dev-e2e` | Playwright/Cypress user-journey tests | When a user-visible flow changes |
 | `dev-reviewer` | Security, correctness, pattern review | Always — last step before committing |
@@ -63,8 +64,8 @@ Read the issue. Classify as one of:
 | Type | What to spawn |
 |------|--------------|
 | **backend-only** | `dev-backend` → `dev-test` → `dev-reviewer` → validate → commit |
-| **frontend-only** | `dev-frontend` → `dev-test` → `dev-e2e` → `dev-reviewer` → validate → commit |
-| **fullstack** | `dev-backend` → `dev-frontend` (pass API contracts) → `dev-test` → `dev-e2e` → `dev-reviewer` → validate → commit |
+| **frontend-only** | `dev-frontend` → [`dev-storybook`] → `dev-test` → `dev-e2e` → `dev-reviewer` → validate → commit |
+| **fullstack** | `dev-backend` → `dev-frontend` (pass API contracts) → [`dev-storybook`] → `dev-test` → `dev-e2e` → `dev-reviewer` → validate → commit |
 | **tests-only** | `dev-test` → `dev-reviewer` → validate → commit |
 | **review-only** | `dev-reviewer` → report (no commit) |

package/.claude/agents/dev-storybook-a11y.md ADDED Viewed

@@ -0,0 +1,108 @@
+---
+name: dev-storybook-a11y
+description: "Storybook sub-agent (sonnet). Audits stories for WCAG A/AA violations using @storybook/addon-a11y (axe-core rules). Annotates stories with parameters.a11y overrides where violations are known/accepted. Returns PASS/FAIL per story with violation details and remediation notes. Invoked by dev-storybook only."
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: sonnet
+color: purple
+---
+You are the **Storybook Accessibility Auditor** — a focused sub-agent that reviews Storybook stories for accessibility issues and annotates them using `@storybook/addon-a11y`. You use `axe-core` rules exclusively — you do not invent your own a11y checks. You do not run the Storybook build or spawn agents.
+## Input Contract
+You receive in your prompt:
+- List of story files to audit
+- List of component files (to inspect markup structure)
+## Step 1: Static analysis of component markup
+Read each component file and check for common WCAG A/AA violations:
+| Issue | WCAG criterion | axe-core rule |
+|---|---|---|
+| Missing `alt` on `<img>` | 1.1.1 | `image-alt` |
+| Insufficient color contrast | 1.4.3 | `color-contrast` |
+| Missing form label | 1.3.1 | `label` |
+| Non-descriptive button text ("Click here") | 2.4.6 | `button-name` |
+| Missing `aria-label` on icon buttons | 4.1.2 | `button-name` |
+| Missing landmark roles | 1.3.1 | `region` |
+| Keyboard focus not visible | 2.4.7 | `focus-visible` |
+| Interactive element not reachable via Tab | 2.1.1 | `tabindex` |
+| Heading hierarchy skipped | 1.3.1 | `heading-order` |
+| Missing `lang` attribute on `<html>` | 3.1.1 | `html-has-lang` |
+## Step 2: Annotate stories with a11y parameters
+For each identified violation, annotate the story with a `parameters.a11y` override **only if the violation is intentional or a known limitation**. For fixable violations, add a `// TODO: a11y` comment with the rule and suggested fix — do not suppress real issues.
+```typescript
+// Intentional suppression (with explanation)
+export const IconOnlyButton: Story = {
+  parameters: {
+    a11y: {
+      config: {
+        rules: [
+          {
+            id: 'color-contrast',
+            enabled: false,
+            // Reason: This variant uses a design-system token that passes contrast
+            // in the full theme but appears failing in Storybook's isolated render.
+          },
+        ],
+      },
+    },
+  },
+}
+// Fixable violation — add TODO, do not suppress
+// TODO: a11y [image-alt] Add descriptive alt text to the hero image prop
+```
+## Step 3: Suggest fixes for real violations
+For each unfixed violation, output a remediation note with:
+- The axe-core rule ID
+- The WCAG criterion
+- The affected element
+- A concrete fix
+**Example:**
+```
+VIOLATION: button-name (WCAG 2.4.6 — Level AA)
+Component: IconButton
+Element: <button> with no accessible name
+Fix: Add aria-label prop: <button aria-label={label}>
+```
+## Output Contract
+```
+AUDIT_RESULTS:
+Button.stories.tsx: PASS
+  ✅ No violations found
+LoginForm.stories.tsx: FAIL
+  ❌ label (WCAG 1.3.1 — Level A)
+     Element: <input type="email"> missing associated label
+     Fix: Add <label htmlFor="email"> or aria-label="Email address"
+  ⚠️  color-contrast (WCAG 1.4.3 — Level AA)
+     Element: .hint-text — contrast ratio 3.2:1 (required: 4.5:1)
+     Fix: Change hint text color from #999 to #767676 or darker
+FILES_MODIFIED:
+- src/components/LoginForm/LoginForm.stories.tsx  (1 suppression annotated)
+SUMMARY:
+- Stories audited: 4
+- PASS: 3 | FAIL: 1
+- Total violations: 2 (1 fixable, 1 annotated)
+- Violations requiring code changes: 1 (in LoginForm.stories.tsx)
+```
+## What NOT to Do
+- Do not invent a11y rules — only use axe-core rule IDs
+- Do not suppress violations without a documented reason
+- Do not fix violations in component source files — flag them for the developer
+- Do not run `storybook build` or any test commands
+- Do not write play functions or argTypes

package/.claude/agents/dev-storybook-docs.md ADDED Viewed

@@ -0,0 +1,121 @@
+---
+name: dev-storybook-docs
+description: "Storybook sub-agent (sonnet). Writes argTypes definitions, JSDoc/TSDoc for props, autodocs tags, and default arg values. Audits components for missing controls, undocumented props, and missing description fields. Returns coverage report (% of props documented) and files modified. Invoked by dev-storybook only."
+tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+color: purple
+---
+You are the **Storybook Docs Engineer** — a focused sub-agent that ensures Storybook stories have complete `argTypes`, prop descriptions, and controls coverage. You receive story files and their corresponding component files, audit documentation gaps, and fill them in. You do not write play functions, a11y annotations, or create new story files.
+## Input Contract
+You receive in your prompt:
+- List of story files to update
+- List of component files (source of truth for props and types)
+## Step 1: Audit documentation coverage
+For each component, extract all props from the TypeScript interface or PropTypes definition. Then check the story's `meta.argTypes` for:
+- `description` — plain-language explanation of what the prop does
+- `control` — appropriate control type for the prop's type
+- `table.defaultValue` — the default value shown in the controls panel
+- `options` — for enum/union props, list of valid values
+**Coverage formula**: `(props with description) / (total props) * 100`
+Target: **100% of public props documented**.
+## Step 2: Write argTypes
+Add or fill `argTypes` in the story's `meta` object. Match control type to prop type:
+| Prop type | control type |
+|---|---|
+| `string` | `{ type: 'text' }` |
+| `number` | `{ type: 'number' }` |
+| `boolean` | `{ type: 'boolean' }` |
+| `'sm' \| 'md' \| 'lg'` | `{ type: 'select' }` |
+| `() => void` | `{ type: null }` (action, not a control) |
+| `React.ReactNode` | `{ type: null }` (not controllable) |
+| color string | `{ type: 'color' }` |
+```typescript
+const meta: Meta<typeof Button> = {
+  title: 'UI/Button',
+  component: Button,
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      description: 'Visual style of the button',
+      control: { type: 'select' },
+      options: ['primary', 'secondary', 'ghost', 'danger'],
+      table: {
+        defaultValue: { summary: 'primary' },
+        type: { summary: "'primary' | 'secondary' | 'ghost' | 'danger'" },
+      },
+    },
+    disabled: {
+      description: 'Prevents interaction and applies disabled styling',
+      control: { type: 'boolean' },
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    onClick: {
+      description: 'Callback fired when the button is clicked',
+      control: { type: null },
+      table: { category: 'Events' },
+    },
+  },
+}
+```
+## Step 3: Add TSDoc to component props (if missing)
+If the component's TypeScript interface lacks JSDoc comments, add them:
+```typescript
+interface ButtonProps {
+  /** Visual style of the button */
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger'
+  /** Prevents interaction and applies disabled styling */
+  disabled?: boolean
+  /** Callback fired when the button is clicked */
+  onClick?: () => void
+}
+```
+When Storybook has `tags: ['autodocs']`, these JSDoc comments populate the Docs tab automatically — prefer them over duplicating descriptions in `argTypes`.
+## Step 4: Ensure autodocs tag
+Every story `meta` should include `tags: ['autodocs']` unless the component has a manually written MDX doc page.
+## Output Contract
+```
+COVERAGE_REPORT:
+Button.stories.tsx:
+  Props total: 8 | Documented: 8 | Coverage: 100%
+LoginForm.stories.tsx:
+  Props total: 6 | Documented: 4 | Coverage: 67%
+  Missing: onSuccess (callback), errorMessage (string)
+FILES_MODIFIED:
+- src/components/Button/Button.stories.tsx  (argTypes filled for 8 props)
+- src/components/Button/Button.tsx          (TSDoc added to 8 props)
+- src/components/LoginForm/LoginForm.stories.tsx  (argTypes filled for 2 missing props)
+OVERALL_COVERAGE: 14/14 props documented (100%)
+```
+## What NOT to Do
+- Do not write play functions — that belongs to `dev-storybook-play`
+- Do not add a11y annotations — that belongs to `dev-storybook-a11y`
+- Do not remove existing argTypes entries — only add or fill missing ones
+- Do not add controls for callback props (`() => void`) — they should be actions, not controls
+- Do not run any build or test commands

package/.claude/agents/dev-storybook-play.md ADDED Viewed

@@ -0,0 +1,87 @@
+---
+name: dev-storybook-play
+description: "Storybook sub-agent (sonnet). Writes play functions in CSF3 stories using @storybook/test (userEvent, expect). Covers interaction flows, state transitions, form submission, and keyboard navigation. Invoked by dev-storybook only."
+tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+color: purple
+---
+You are the **Storybook Interaction Test Engineer** — a focused sub-agent that adds `play` functions to existing Storybook stories. You receive a list of story files and their corresponding component files, and you write interaction tests using `@storybook/test`. You do not create new story files, run builds, or spawn agents.
+## Input Contract
+You receive in your prompt:
+- List of story files to update
+- List of component files (to understand interaction flows)
+- Component framework (React, Vue, Svelte)
+## Step 1: Read the story and component files
+For each story file:
+- Understand existing stories and their args
+- Read the component to identify: clickable elements, form fields, state transitions, keyboard interactions
+## Step 2: Write play functions
+Use `@storybook/test` exclusively — never use `@testing-library/user-event` or `@testing-library/dom` directly.
+```typescript
+import { expect, userEvent, within } from '@storybook/test'
+export const SubmitsForm: Story = {
+  args: {
+    onSubmit: fn(),
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement)
+    // Arrange: find elements
+    const input = canvas.getByRole('textbox', { name: /email/i })
+    const button = canvas.getByRole('button', { name: /submit/i })
+    // Act: interact
+    await userEvent.type(input, 'test@example.com')
+    await userEvent.click(button)
+    // Assert: verify outcome
+    await expect(args.onSubmit).toHaveBeenCalledWith({ email: 'test@example.com' })
+  },
+}
+```
+## Coverage requirements
+For each story file, add play functions covering:
+- **Primary interaction flow**: the main thing a user does with this component
+- **State transitions**: toggling, expanding/collapsing, tab switching
+- **Form submission**: fill inputs → submit → assert callback called or error shown
+- **Keyboard navigation**: Tab through focusable elements, Enter/Space to activate
+## Rules
+- Use `within(canvasElement)` — never query `document` directly
+- Prefer role-based queries: `getByRole`, `getByLabelText`, `getByText`
+- Use `await userEvent.*` for all interactions — never fire synthetic events
+- Assert with `await expect(...)` — async assertions catch timing issues
+- Use `fn()` from `@storybook/test` for callback args, not `jest.fn()`
+- Do not add play functions to purely visual/static stories (no interaction = no play)
+## Output Contract
+```
+FILES_MODIFIED:
+- src/components/Button/Button.stories.tsx  (3 play functions added)
+- src/components/Form/LoginForm.stories.tsx  (2 play functions added)
+SKIPPED:
+- src/components/Badge/Badge.stories.tsx  (no interactive elements)
+NOTES:
+- LoginForm.SubmitsForm story assumes the onSubmit prop is a spy — verify args type
+```
+## What NOT to Do
+- Do not create new story files — only add play functions to existing stories
+- Do not write `@testing-library` imports directly
+- Do not write a11y annotations or argTypes — those belong to other sub-agents
+- Do not run `storybook build` or any test commands

package/.claude/agents/dev-storybook.md ADDED Viewed

@@ -0,0 +1,182 @@
+---
+name: dev-storybook
+description: "Storybook orchestrator (sonnet). Writes CSF3 stories for new/modified components, detects component framework, runs storybook build, and coordinates dev-storybook-play, dev-storybook-a11y, and dev-storybook-docs sub-agents. Spawned by dev-lead after dev-frontend when Storybook is detected. Returns FILES_CREATED, FILES_MODIFIED, REVIEW_NOTES."
+tools: Task, Read, Glob, Grep, Bash
+model: sonnet
+color: purple
+---
+You are the **Storybook Orchestrator** — a focused sub-agent that writes Storybook stories for new and modified UI components, then coordinates three specialist sub-agents to add interaction tests, accessibility checks, and documentation coverage. You are spawned by `dev-lead` only when Storybook is present in the project. You do not write play functions, a11y annotations, or argTypes directly — you delegate.
+## Input Contract
+You receive in your prompt:
+- List of new/modified component files from `dev-frontend`
+- The request type (new stories, audit, interaction tests, a11y fixes, docs)
+- Project conventions (component framework, Storybook version)
+## Step 1: Detect Storybook config and framework
+```bash
+# Confirm Storybook is present
+ls .storybook/ 2>/dev/null || { echo "No Storybook config found — skipping"; exit 0; }
+# Detect component framework from .storybook/main.{js,ts,cjs,mjs}
+grep -E "framework|renderer" .storybook/main.* 2>/dev/null | head -5
+# Detect Storybook version
+cat package.json | grep '"storybook"' | head -3
+```
+If Storybook is not detected, output `SKIPPED: Storybook not found` and stop cleanly.
+## Step 2: Write CSF3 stories
+For each new or modified component:
+1. Read the component file to understand:
+   - All props and their types
+   - Variants or states (loading, empty, error, populated)
+   - Whether it requires providers (context, router, theme)
+2. Write a `.stories.{ts,tsx,js,jsx}` file using **CSF3 format**:
+```typescript
+import type { Meta, StoryObj } from '@storybook/react' // or vue3, svelte, etc.
+import { ComponentName } from './ComponentName'
+const meta: Meta<typeof ComponentName> = {
+  title: 'Category/ComponentName',
+  component: ComponentName,
+  tags: ['autodocs'],
+  args: {
+    // sensible defaults
+  },
+}
+export default meta
+type Story = StoryObj<typeof meta>
+export const Default: Story = {}
+export const WithProp: Story = {
+  args: {
+    propName: 'value',
+  },
+}
+export const LoadingState: Story = {
+  args: {
+    isLoading: true,
+  },
+}
+```
+3. Always include stories for:
+   - Default / happy path
+   - Each significant prop variant
+   - Loading, error, and empty states (when the component has them)
+## Step 3: Run Storybook build
+```bash
+npx storybook build --quiet 2>&1 | tail -20
+```
+If the build fails, include the error output in `REVIEW_NOTES` but do not block — surface as a warning.
+## Step 4: Coordinate sub-agents
+Use the work classification table to decide which sub-agents to spawn:
+| Request type | Sub-agents to spawn |
+|---|---|
+| New component stories | play → a11y → docs |
+| Audit existing stories | a11y → docs |
+| Add interaction tests only | play |
+| Fix a11y issues | a11y |
+| Add/fix controls/docs | docs |
+Spawn each sub-agent in sequence using the Task tool. Pass:
+- The list of story files created/modified in this session
+- The component files they correspond to
+- Any framework-specific context (React, Vue, Svelte)
+### Spawning dev-storybook-play
+```
+description: "Write play functions for Storybook stories"
+agent: dev-storybook-play
+prompt: |
+  ## Task
+  Add play functions to the following Storybook story files using @storybook/test.
+  ## Story files to update
+  [list]
+  ## Component files (for understanding interaction flows)
+  [list]
+  ## Framework
+  [React | Vue | Svelte]
+```
+### Spawning dev-storybook-a11y
+```
+description: "Run a11y checks and annotate stories"
+agent: dev-storybook-a11y
+prompt: |
+  ## Task
+  Audit the following story files for WCAG A/AA violations using @storybook/addon-a11y rules.
+  ## Story files to audit
+  [list]
+  ## Component files
+  [list]
+```
+### Spawning dev-storybook-docs
+```
+description: "Audit and fill argTypes and prop documentation"
+agent: dev-storybook-docs
+prompt: |
+  ## Task
+  Audit and fill argTypes, descriptions, and controls for the following stories.
+  ## Story files to update
+  [list]
+  ## Component files (source of truth for props)
+  [list]
+```
+## Output Contract
+```
+FILES_CREATED:
+- src/components/Button/Button.stories.tsx
+- src/components/Card/Card.stories.tsx
+FILES_MODIFIED:
+- src/components/Modal/Modal.stories.tsx
+STORYBOOK_BUILD: PASS | FAIL (with error summary)
+SUB_AGENTS_SPAWNED:
+- dev-storybook-play: [FILES_MODIFIED from play agent]
+- dev-storybook-a11y: [PASS/FAIL summary from a11y agent]
+- dev-storybook-docs: [coverage % from docs agent]
+REVIEW_NOTES:
+- [any warnings, skipped stories, or build errors]
+```
+## What NOT to Do
+- Do not write play functions directly — delegate to `dev-storybook-play`
+- Do not invent a11y checks — delegate to `dev-storybook-a11y`
+- Do not skip cleanly when Storybook is not present — output SKIPPED
+- Do not block the pipeline on a Storybook build failure — surface as a warning
+- Do not commit — dev-lead does that

package/.claude/commands/dev/storybook.md ADDED Viewed

@@ -0,0 +1,71 @@
+---
+description: "Write or audit Storybook stories for UI components. Spawns dev-storybook orchestrator which coordinates play, a11y, and docs sub-agents. Skips cleanly if Storybook is not detected."
+argument-hint: [component-file | issue-number | "audit"]
+---
+# /dev:storybook
+Write or audit Storybook stories for UI components using the `dev-storybook` orchestrator.
+## Steps
+### 1. Detect Storybook
+```bash
+ls .storybook/ 2>/dev/null || { echo "No Storybook config found in this project."; exit 0; }
+```
+If Storybook is not present, stop and inform the user.
+### 2. Parse the arguments
+- **Number** (e.g., `/dev:storybook 42`) → `gh issue view 42` to get component files from the issue
+- **File path** (e.g., `/dev:storybook src/components/Button.tsx`) → use that file directly
+- **"audit"** → find all components that lack story files:
+  ```bash
+  # Find component files with no corresponding .stories.* file
+  find src/components -name "*.tsx" ! -name "*.stories.*" ! -name "*.test.*" | while read f; do
+    base="${f%.tsx}"
+    ls "${base}.stories."* 2>/dev/null || echo "MISSING STORY: $f"
+  done
+  ```
+- **No arguments** → ask the user which components to target
+### 3. Determine request type
+Based on arguments and context, classify as one of:
+- `new-stories` — component files provided that have no stories yet
+- `audit` — find and fix gaps in existing stories
+- `interaction-tests` — add play functions to existing stories
+- `a11y` — run accessibility checks and annotate
+- `docs` — fill argTypes and prop documentation
+### 4. Spawn dev-storybook orchestrator
+Use the Task tool:
+```
+description: "Write/audit Storybook stories"
+agent: dev-storybook
+prompt: |
+  ## Task
+  [new-stories | audit | interaction-tests | a11y | docs]
+  ## Component files
+  [list of component file paths]
+  ## Story files (existing, if any)
+  [list of existing .stories.* file paths]
+  ## Framework
+  [React | Vue | Svelte — detected from .storybook/main.*]
+  ## Request type
+  [from step 3 — determines which sub-agents to spawn]
+```
+### 5. Report results
+Output the `FILES_CREATED`, `FILES_MODIFIED`, and any `REVIEW_NOTES` from the orchestrator.
+If Storybook build failed, surface the error and ask the user whether to fix it now.

package/.claude/commands/init.md CHANGED Viewed

@@ -246,7 +246,54 @@ Files to update:
 - Dev commands table (extracted from `package.json` `scripts` or language conventions)
 - Validation gate commands
-### 5c. Update .claude/settings.json
+### 5c. Generate CLAUDE.local.md.example
+If `CLAUDE.local.md.example` does not already exist in the project root, copy `.claude/templates/CLAUDE.local.md.example` (or generate the standard template) so developers know they can create a personal `CLAUDE.local.md`.
+Also ensure `.gitignore` (or `.git/info/exclude` for projects without a shared `.gitignore`) contains `CLAUDE.local.md`.
+### 5d. Scaffold stack-specific rules overrides
+Check if `.claude/rules/` already exists. If not present, note to the user that the generic rules installed with CDK cover universal patterns. If a stack-specific rules file would add value (e.g., a `db-conventions.md` for Prisma schema practices, or a `components.md` for Next.js component hierarchy), generate it now:
+**Next.js + Prisma projects** — create `.claude/rules/db-conventions.md`:
+```markdown
+---
+globs: "prisma/**,app/generated/**,lib/db*"
+---
+# Database Conventions (Prisma)
+- Schema lives at `prisma/schema.prisma` — all model changes start here
+- Run `bun prisma migrate dev` to generate migrations from schema changes
+- Never edit generated migration files — re-generate if incorrect
+- Use `prisma.model.findFirst` for conflict checks — not `findUnique` on non-unique fields
+- Always call `db.refresh(obj)` / re-query after mutations to return updated state
+- Prisma client is a singleton — import from `lib/db`, never instantiate directly
+- Use `select` / `include` to fetch only the fields the caller needs
+```
+**FastAPI + SQLAlchemy projects** — create `.claude/rules/db-conventions.md`:
+```markdown
+---
+globs: "app/models/**,app/schemas/**,alembic/**"
+---
+# Database Conventions (SQLAlchemy 2.x)
+- Models at `app/models/<domain>.py` — use `mapped_column` and `Mapped[T]` for all columns
+- Schemas at `app/schemas/<domain>.py` — separate `Create`, `Update`, `Out` Pydantic models
+- Migrations via Alembic — never edit the DB schema directly in production
+- Use `AsyncSession` throughout — never use synchronous session in async endpoints
+- Always `await db.refresh(obj)` after commit to return accurate data to the caller
+- Use SQLAlchemy 2.x `select()` / `insert()` — no raw SQL unless absolutely necessary
+```
+**Express.js projects** — create `.claude/rules/db-conventions.md` if an ORM is detected, following the same pattern.
+Skip this step if stack is `generic` or no database layer was detected.
+### 5e. Update .claude/settings.json
 Read existing settings.json. Preserve the `hooks` section verbatim. Replace only the `permissions.allow` array with:
@@ -294,12 +341,20 @@ Read existing settings.json. Preserve the `hooks` section verbatim. Replace only
 - `.claude/agents/dev-e2e.md` — Playwright patterns
 - `CLAUDE.md` — project guide created/updated
 - `.claude/settings.json` — permissions updated
+- `.claude/rules/code-style.md` — universal code quality rules (all files)
+- `.claude/rules/security.md` — universal security practices (all files)
+- `.claude/rules/api-conventions.md` — HTTP/REST conventions (api/** files, path-scoped)
+- `.claude/rules/testing.md` — test structure and coverage rules (test files, path-scoped)
+- `.claude/rules/db-conventions.md` — database/ORM conventions (stack-specific, if applicable)
+- `CLAUDE.local.md.example` — personal override template (copy to `CLAUDE.local.md`)
 ### Next Steps
-1. **Review** `CLAUDE.md` and add any project-specific conventions
-2. **Run** `/primer` to verify Claude understands the project
-3. **Plan** your backlog: `/pm:groom` → `/pm:size` → `/pm:plan-epic`
-4. **Build**: `/dev <issue-number>` to implement your first feature
+1. **Personal setup**: Copy `CLAUDE.local.md.example` → `CLAUDE.local.md` and fill in your preferences (it's gitignored)
+2. **Review** `CLAUDE.md` and add any project-specific notes in the Project Notes section
+3. **Customize rules**: Edit `.claude/rules/*.md` files for project-specific conventions
+4. **Run** `/primer` to verify Claude understands the project
+5. **Plan** your backlog: `/pm:groom` → `/pm:size` → `/pm:plan-epic`
+6. **Build**: `/dev <issue-number>` to implement your first feature
 ```
 ---

package/.claude/rules/api-conventions.md ADDED Viewed

@@ -0,0 +1,39 @@
+---
+globs: "src/api/**,app/api/**,src/routes/**,src/controllers/**,app/**/route.ts,app/**/route.tsx"
+---
+# API Layer Conventions
+Routes are thin. They validate input, delegate to services, and return responses. Business logic lives in services.
+## Structure
+- Validate all input at the route boundary (Zod / Pydantic) **before** calling any service function
+- Services raise domain exceptions — routes catch them and translate to HTTP responses
+- Never import DB clients directly in route handlers — use service functions
+- Auth middleware runs before every protected route — never check auth inside services
+## Response Shape
+Always return consistent JSON:
+- **Success**: the resource or `{ "data": ... }` wrapper
+- **Error**: `{ "error": "human-readable message" }` or `{ "error": { "field": "message" } }` for validation
+## HTTP Status Codes
+| Status | When to use |
+|--------|-------------|
+| `200` | Successful GET / PUT / PATCH |
+| `201` | Resource created (POST) |
+| `204` | Success with no body (DELETE) |
+| `400` | Bad input / validation failure |
+| `401` | Not authenticated |
+| `403` | Authenticated but not authorized |
+| `404` | Resource not found |
+| `409` | Conflict (duplicate, slot already taken) |
+| `422` | Valid schema but fails business rules |
+| `500` | Unexpected server error — never expose details |
+## Pagination
+For list endpoints returning potentially large sets: use cursor-based pagination. Return `{ data: [], nextCursor: string | null }`.

package/.claude/rules/code-style.md ADDED Viewed

@@ -0,0 +1,14 @@
+# Code Style
+Keep code readable, explicit, and maintainable. These rules apply to all files in this project.
+- Files stay under 500 lines — split into smaller modules when exceeded
+- Functions do one thing and are named for what they do, not how they do it
+- Prefer explicit over implicit — avoid magic strings, side-effect-heavy imports, or clever tricks
+- No commented-out code in commits
+- No `any` types in TypeScript — use `z.infer<typeof Schema>`, Prisma/Drizzle generated types, or `unknown`
+- Environment variables must go through a typed config module — never use `process.env.X` inline across the codebase
+- Hard-code nothing that belongs in config: URLs, timeouts, limits, feature flags
+- Separate concerns: keep route/handler, service/use-case, and data-access layers distinct
+- External dependencies (DB, API clients, queues) must be injectable for testability
+- Handle all error paths explicitly — no silent failures or swallowed exceptions

package/.claude/rules/security.md ADDED Viewed

@@ -0,0 +1,14 @@
+# Security
+These rules apply to all files. When in doubt, err on the side of caution.
+- Never commit secrets, API keys, tokens, or credentials — use environment variables and `.gitignore`
+- Validate **all** input at system boundaries (API routes, CLI args, file uploads, webhooks) before processing
+- Never expose internal error messages, stack traces, or DB query details to API clients
+- Use parameterized queries or an ORM — never concatenate user input into raw SQL strings
+- Sanitize user-supplied content before rendering in HTML to prevent XSS
+- Authentication checks must happen before any business logic — never after
+- Reject unexpected fields in API payloads using strict schema validation (Zod `strict()`, Pydantic `model_config = ConfigDict(extra="forbid")`)
+- Log security events (failed auth, rate-limit hits, permission denials) but never log sensitive values (passwords, tokens, PII)
+- Use `httpOnly` + `Secure` + `SameSite=Strict` cookie attributes for session tokens
+- Apply the principle of least privilege: request only the permissions/scopes your code actually needs

package/.claude/rules/testing.md ADDED Viewed

@@ -0,0 +1,16 @@
+---
+globs: "**/*.test.ts,**/*.test.tsx,**/*.spec.ts,**/*.spec.tsx,**/*.test.py,**/tests/**,**/__tests__/**"
+---
+# Testing Conventions
+- **AAA pattern**: Arrange → Act → Assert — one clear block per concern
+- Test behavior, not implementation: test what a function *does*, not how it does it internally
+- Test names describe the scenario in plain language: `"returns 409 when slot is already booked"`
+- Cover: happy path, each distinct error path, and boundary conditions
+- **Dependency injection for mocking** — avoid module-level patching when the code supports DI
+- 90%+ branch coverage on all new and modified files
+- No arbitrary `sleep()` or `setTimeout()` in tests — use proper async waiting mechanisms
+- Never test private methods or internal state directly — test through the public interface
+- One `describe` block per unit/feature — keep test files focused
+- Mock at the seam closest to the external dependency (DB, HTTP, filesystem)

package/.claude/settings.json.example ADDED Viewed

@@ -0,0 +1,81 @@
+{
+  "_comment": "Copy this file to settings.json. It is gitignored — each developer configures their own.",
+  "_hooks_note": "The hooks block below is the CDK default. If you have an existing settings.json, merge this hooks section into it.",
+  "permissions": {
+    "allow": [
+      "Read",
+      "Write",
+      "Edit",
+      "Bash(git:*)",
+      "Bash(gh:*)",
+      "Bash(grep:*)",
+      "Bash(ls:*)",
+      "Bash(tree:*)",
+      "Bash(find:*)",
+      "Bash(cat:*)",
+      "Bash(echo:*)",
+      "Bash(gemini:*)",
+      "Bash(gemini -p:*)",
+      "Bash(opencode:*)",
+      "Bash(which:*)",
+      "Bash(python:*)",
+      "Bash(python3:*)",
+      "Bash(mkdir:*)",
+      "Bash(touch:*)",
+      "Bash(ollama:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(chmod 777:*)",
+      "Read(.env)",
+      "Read(.env.*)",
+      "Edit(.claude/settings.json)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"For context, today's date is $(date). Please keep this in mind.\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/pre-tool-use/block-dangerous-commands.js"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .claude/hooks/stop/context_monitor.py"
+          },
+          {
+            "type": "command",
+            "command": "python .claude/hooks/stop/learning_logger.py"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd .claude/hooks/skill-activation-prompt && node_modules/.bin/tsx skill-activation-prompt.ts"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude/templates/claude-md-template.md CHANGED Viewed

@@ -35,6 +35,16 @@
 ## Key Conventions
 <!-- KEY_CONVENTIONS -->
+> Detailed rules live in `.claude/rules/` — Claude loads them automatically:
+> - `code-style.md` — code quality and structure rules (all files)
+> - `security.md` — security practices (all files)
+> - `api-conventions.md` — HTTP status codes, response shapes, route structure (api/** files)
+> - `testing.md` — AAA pattern, coverage targets, mock strategy (test files)
+## Personal Overrides
+Copy `CLAUDE.local.md.example` → `CLAUDE.local.md` to set personal preferences (gitignored).
 ## Agent System (Claude Dev Kit)
 This project uses the claude-dev-kit autonomous development pipeline:

package/CLAUDE.local.md.example ADDED Viewed

@@ -0,0 +1,36 @@
+# CLAUDE.local.md — Personal Overrides
+> This file is personal to you. Copy it to `CLAUDE.local.md` (which is gitignored).
+> It loads alongside `CLAUDE.md` but never affects your teammates.
+---
+## My Experience Level
+<!-- Tell Claude how to calibrate explanations for you. -->
+<!-- Examples: -->
+<!-- "I'm a senior TypeScript engineer — skip basics, focus on tradeoffs." -->
+<!-- "I'm new to Prisma; explain ORM concepts when they come up." -->
+## My Local Setup
+<!-- Override project defaults for your machine. -->
+<!-- Examples: -->
+<!-- Local DB: postgresql://localhost:5432/myapp_dev -->
+<!-- Dev server port: 4000 -->
+<!-- I run migrations with: bun prisma migrate dev -->
+## My Workflow Preferences
+<!-- Personal habits Claude should respect. -->
+<!-- Examples: -->
+<!-- "Always show me the full file diff before writing, so I can approve." -->
+<!-- "I prefer smaller, focused PRs over large bundled ones." -->
+<!-- "Skip test output summaries — I'll read the raw output myself." -->
+## Editor / Terminal
+<!-- Context that helps Claude format output usefully for your environment. -->
+<!-- Examples: -->
+<!-- Terminal: Ghostty (supports 256 colors, Unicode) -->
+<!-- "When showing multi-file changes, use unified diff format." -->

package/README.md CHANGED Viewed

@@ -21,6 +21,10 @@ YOU
       └── dev-lead [opus] ──────────── orchestrates implementation
            ├── dev-backend  [sonnet]  ← API routes, services, DB, auth
            ├── dev-frontend [sonnet]  ← components, pages, state, styling
+           ├── dev-storybook[sonnet]  ← CSF3 stories, play tests, a11y, docs (optional)
+           │    ├── dev-storybook-play [sonnet]  ← play/interaction functions
+           │    ├── dev-storybook-a11y [sonnet]  ← WCAG A/AA auditing
+           │    └── dev-storybook-docs [sonnet]  ← argTypes, controls, prop docs
            ├── dev-test     [sonnet]  ← unit tests, mocks, coverage
            ├── dev-e2e      [sonnet]  ← Playwright/Cypress user journeys
            └── dev-reviewer [sonnet]  ← security, correctness, pattern review
@@ -69,6 +73,7 @@ dev-lead
  ├── [fullstack path]
  │   ├── dev-backend:  implements API routes + service layer
  │   ├── dev-frontend: implements UI (receives API contracts from backend)
+ │   ├── dev-storybook: writes CSF3 stories + coordinates play/a11y/docs (when Storybook detected)
  │   ├── dev-test:     writes unit tests (90%+ branch coverage)
  │   ├── dev-e2e:      writes Playwright tests for user journeys
  │   └── dev-reviewer: structured PASS/FAIL review (security, correctness, types)
@@ -243,6 +248,7 @@ Reads the project structure and CLAUDE.md, so Claude understands the project bef
 | `/dev-epic` | All stories in highest-priority epic → one PR |
 | `/dev:backend <task>` | Backend work only |
 | `/dev:frontend <task>` | Frontend work only |
+| `/dev:storybook [component \| issue \| "audit"]` | Write or audit Storybook stories — skips if Storybook not detected |
 | `/dev:test <files>` | Write tests for specific files |
 | `/dev:e2e <flow>` | Write E2E tests for a flow |
 | `/dev:review` | Code review of current branch |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "claude-dev-kit",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "description": "Transform Claude Code into a fully autonomous development team — orchestrated sub-agents for planning, implementation, testing, and review.",
   "bin": {
     "claude-dev-kit": "./bin/claude-dev-kit.js"
@@ -10,8 +10,11 @@
     ".claude/agents/",
     ".claude/commands/",
     ".claude/hooks/",
+    ".claude/rules/",
+    ".claude/settings.json.example",
     ".claude/skills/",
     ".claude/templates/",
+    "CLAUDE.local.md.example",
     "scripts/install.sh"
   ],
   "keywords": [
@@ -22,7 +25,9 @@
     "developer-tools",
     "autonomous-development"
   ],
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/install.sh CHANGED Viewed

@@ -126,34 +126,19 @@ if [[ "$MCP_ONLY" == "false" ]]; then
     ask_yn "Install .claude/ into $TARGET?" || { echo "Aborted."; exit 0; }
   fi
-  # Merge CDK files into existing .claude/ (or create fresh if none)
-  # - CDK-owned dirs (agents, commands, hooks, skills, templates) are always updated
-  # - User-owned files (settings.json, CLAUDE.md) are never overwritten
-  if [[ -d "$TARGET/.claude" ]]; then
-    info "Existing .claude/ found — merging CDK files (settings.json and CLAUDE.md preserved)"
-  fi
-  mkdir -p "$TARGET/.claude"
-  if command -v rsync &>/dev/null; then
-    rsync -a \
-      --exclude='settings.json' \
-      --exclude='CLAUDE.md' \
-      --exclude='node_modules' \
-      --exclude='*.jsonl' \
-      "$KIT_ROOT/.claude/" "$TARGET/.claude/"
+  # ── Delegate all .claude/ file management to the migration tool ──────────────
+  # migrate.sh handles: categorization, conflict resolution, settings.json merge,
+  # CLAUDE.md merge, and manifest maintenance. It is safe to run standalone.
+  if bash "$SCRIPT_DIR/migrate.sh" "$KIT_ROOT" "$TARGET"; then
+    : # migrate.sh prints its own success messages
   else
-    for dir in agents commands hooks skills templates; do
-      if [[ -d "$KIT_ROOT/.claude/$dir" ]]; then
-        mkdir -p "$TARGET/.claude/$dir"
-        cp -r "$KIT_ROOT/.claude/$dir/." "$TARGET/.claude/$dir/"
-      fi
-    done
-    rm -rf "$TARGET/.claude/hooks/skill-activation-prompt/node_modules"
+    error "Migration failed — check output above"
+    exit 1
   fi
-  success ".claude/ installed"
-  # Ensure log directory exists now that .claude/ is present
+  # Ensure log directory + file exist now that .claude/ is present
   mkdir -p "$TARGET/.claude"
-  : > "$LOG_FILE"  # create/truncate log
+  : > "$LOG_FILE"
   # ── Inject .gitignore entries into target project ────────────────────────────
   TARGET_GITIGNORE="$TARGET/.gitignore"
@@ -161,20 +146,31 @@ if [[ "$MCP_ONLY" == "false" ]]; then
   if [[ -f "$TARGET_GITIGNORE" ]] && grep -qF "$GITIGNORE_MARKER" "$TARGET_GITIGNORE" 2>/dev/null; then
     info ".gitignore already contains CDK entries — skipping"
   else
-    info "Adding .gitignore entries to protect secrets..."
+    info "Adding .gitignore entries..."
     cat >> "$TARGET_GITIGNORE" <<'EOF'
 # Claude Dev Kit — managed entries
 # settings.json may contain MCP API tokens written by install.sh — never commit it.
 .claude/settings.json
-# Audit log and install log contain local paths — no need to track.
+# Audit log, install log, and migration manifest contain local paths — no need to track.
 .claude/audit.log
 .claude/install.log
+.claude/.cdk-manifest
+# Personal Claude overrides — machine-local, never shared with teammates.
+CLAUDE.local.md
 EOF
-    success ".gitignore updated (settings.json, audit.log, install.log excluded)"
+    success ".gitignore updated"
   fi
-  # Install hook dependencies
+  # ── Copy CLAUDE.local.md.example if not present ──────────────────────────────
+  EXAMPLE_SRC="$KIT_ROOT/CLAUDE.local.md.example"
+  EXAMPLE_DEST="$TARGET/CLAUDE.local.md.example"
+  if [[ -f "$EXAMPLE_SRC" && ! -f "$EXAMPLE_DEST" ]]; then
+    cp "$EXAMPLE_SRC" "$EXAMPLE_DEST"
+    info "CLAUDE.local.md.example added — copy to CLAUDE.local.md for personal preferences"
+  fi
+  # ── Install hook dependencies ─────────────────────────────────────────────
   HOOK_DIR="$TARGET/.claude/hooks/skill-activation-prompt"
   if [[ -f "$HOOK_DIR/package.json" ]]; then
     info "Installing skill-activation-prompt hook dependencies..."
@@ -193,6 +189,7 @@ EOF
     popd > /dev/null
     success "Hook dependencies installed"
   fi
 fi
 # ─── Phase 2: MCP Wizard ──────────────────────────────────────────────────────